# Dependencies & Specs
Source: https://docs.encord.com/agents-documentation/Basics/Dependencies



## Dependencies

When writing agents, you often rely on common resources, whether data for running your agent or for recording the output. Encord Agents use **dependency injection** to declaratively acquire these resources, so you can focus on developing your agent instead of writing boilerplate to set them up manually.

### What is Dependency Injection?

Dependency injection means your code (in this case, your path operation functions) can declare what it needs to function — its "dependencies." The system (e.g., FastAPI or encord-agents) then takes care of providing your code with those dependencies ("injecting" them).

We follow the same pattern as [FastAPI Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/), where you can find more examples.

### Injecting Dependencies

When defining your agents, you can inject essential dependencies, such as the path to the underlying asset or frame iterators. You can also add custom dependencies if needed.

To inject dependencies, type-annotate your agent function variables using the `Depends` class. In the example below, replace `{module}` with the type of agent you're building:

```python theme={"dark"}
from typing_extensions import Annotated

from encord.core.dependencies import Depends
# or from fastapi import Depends # if you are building a fastapi app

from encord.{module}.dependencies import dep_single_frame

def my_agent(frame: Annotated[np.ndarray, Depends(dep_single_frame)]):
    # the frame becomes available here.
```

See the [references section](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#dependencies-2) for available dependencies.

### Custom Dependencies

To add a custom dependency:

```python theme={"dark"}
def my_custom_dependency(label_row: LabelRowV2) -> dict:
    # 1. Define a function to load the dependency
    # e.g., look up additional data in own db
    return db.query("whatever")

@runner.stage(stage="<my_stage_name>")
def by_custom_data(
    # 2. Use that function as a dependency
    custom_data: Annotated[dict, Depends(my_custom_dependency)]
) -> str:
    # `custom_data` is automatically injected here.
    # ... do your thing
    # then, return name of task pathway.
```

Custom dependency functions can themselves rely on other dependencies, enabling more complex resource acquisition — see `dep_video_iterator` for an example of this.

***

## Custom Agents Specification

This section defines the interface for Custom Agents. Use it to define agents via the library or when writing your own implementation.

### Schema

```typescript theme={"dark"}
type AgentPayload = {
  projectHash: string;
  dataHash: string;
  frame: number;
  objectHashes?: string[];
};
```

This schema aligns with the **FrameData** structure. The `objectHashes` field is optional — when present, it's a list of strings.

### Test Payload

When you register your Custom Agent in the platform's **Custom Agents** section, you can test it with a test payload.

* If you modify the test payload, the platform verifies that your agent has access to the associated project and data.
* If you leave it unmodified, the platform instead sends a distinguished `X-Encord-Agent` header, which automatically triggers an appropriate response.

This lets you confirm that your agent is deployed correctly, that your session can see the agent (all requests to your agent originate from your browser session, not the Encord backend), and that it works on specific Projects.

### Webhook Security

Encord provides webhook signing secrets to verify the authenticity of requests sent to your custom agent endpoints. Each custom agent endpoint receives a unique signing secret you can use to validate incoming webhook payloads.

**To access your signing secret**:

1. Navigate to your Workflow configuration in Encord.
2. Select your custom agent node.
3. Locate the **Signing secret** section.
4. Use the eye icon to reveal the secret, or the copy icon to copy it to your clipboard.

<Note>The signing secret is automatically generated when you configure your custom agent endpoint URL. Save your workflow after changing the URL to update the secret.</Note>

*To verify webhook signatures*:

Use the signing secret to verify that webhook requests to your custom agent endpoint originate from Encord. This helps protect your endpoint from unauthorized requests and ensures data integrity.

For implementation guidance, see the [webhook security documentation](/platform-documentation/Annotate/annotate-webhooks-notifications#verifying-webhook-signatures).

### Response

The platform displays your agent's output using the **AgentResponse** type, making your agents more interactive and informative. For example, if the label state doesn't meet the Custom Agent's expectations, or if the agent's function is to check the validity of current labels, the response type lets you communicate that information to the annotator.

### Error Handling

Raise an `EncordAgentException` to handle errors appropriately. For example, if your agent expects polygons but receives a skeleton, use it to return an informative error to the Encord platform.

If an **authorization issue** occurs with the Encord platform (for example, a request tries to access a project the agent doesn't have access to), the response body includes the authorization message in an `AgentErrorResponse` type:

```typescript theme={"dark"}
type EditorAgentErrorResponse = {
  message?: string;
}
```

The platform displays this message so your agent can be used intuitively.


# AWS Lambda Functions
Source: https://docs.encord.com/agents-documentation/Custom-Agents/AWS-Lambda



<Warning>
  Before you start, ensure that you can [authenticate](/agents-documentation/Basics/Authentication) with Encord and your [AWS CLI is authenticated](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-authentication.html).
</Warning>

The following example shows the general structure of how to build an AWS Lambda function. For concrete implementations of agents with specific abilities, see the [examples section](/agents-documentation/Custom-Agents/Examples).

There are two different ways in which you can create lambda functions.

1. [Using a zip upload](#building-a-lambda-function-using-zip-upload)
2. [Using a Docker container](#building-a-lambda-function-with-docker)

They have different applications and properties.
Before you dive into one of the examples, please consider the properties in the table below.

| Type                                                       |    File size limits   | Ease of use |
| :--------------------------------------------------------- | :-------------------: | :---------: |
| [Zip upload](#building-a-lambda-function-using-zip-upload) | 50MB (250MB unzipped) |   `easier`  |
| [Docker](#building-a-lambda-function-with-docker)          |           NA          |   `harder`  |

AWS Lambda zip deployments have a 50MB (250MB uncompressed) size limit. This often forces the use of Docker for agents with larger dependencies, such as computer vision libraries (`pip install encord-agents[vision]`). Additionally, dependencies relying on C/C++ code require specific CPU architecture installations, often making testing only possible after deployment.

More detailed AWS Documentation on python lambda functions can be found [here](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python.html).

## Building a lambda function using zip upload

The full AWS lambda documentation for zip files is available [here](https://docs.aws.amazon.com/lambda/latest/dg/python-package.html).

### STEP 1: Create a local Project

To begin, set up your local project structure. This includes creating two directories, a virtual environment (for example `venv`), and a package directory for CPU-architecture-specific dependencies tailored to your cloud infrastructure.

1. Create your virtual environment and install `encord-agents`. Refer to the [installation docs](/agents-documentation/Basics/Installation) for detailed instructions.

```shell theme={"dark"}
mkdir my_project
cd my_project
python -m venv venv
source venv/bin/activate
pip install encord-agents
deactivate
```

2. Create the "mirror" package directory for the upload.

<Note>
  We recommend explicitly installing `boto3`, the AWS SDK, even though it's typically present in Lambda environments. This ensures consistent dependency versions and avoids unexpected changes when AWS updates its infrastructure.
</Note>

```shell theme={"dark"}
mkdir package
pip install \
  --platform manylinux2014_x86_64 \
  --target=package \
  --implementation cp \
  --python-version 3.12 \
  --only-binary=:all: --upgrade \
  encord-agents boto3
```

### STEP 2: Define the agent

1. Create a `lambda_function.py` file using the following template:

```python title="lambda_function.py" theme={"dark"}
from encord.objects.ontology_labels_impl import LabelRowV2

from encord_agents.core.data_model import FrameData
from encord_agents.aws import editor_agent


@editor_agent()
def lambda_handler(frame_data: FrameData, label_row: LabelRowV2) -> None:
    print(frame_data.model_dump_json())
    # label_row.save()
```

<Note>
  Make sure to name your file `lambda_function.py` and your function `lambda_handler` if you are following this example, as these names are referenced in the `--handler` argument in [Step 6](#step-6-upload-the-zip).
</Note>

2. Complete the `lambda_handler` function with the logic you want to execute when the agent is triggered.

<Tip>
  For more Custom Agent examples, see the [examples section](/agents-documentation/Custom-Agents/Examples).
  You can inject multiple different [dependencies](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#Dependencies) into the function if necessary.
</Tip>

### STEP 3: (Optional) Test the Agent Locally

<Warning>
  We are testing against the `venv` and not the `package` that is uploaded to AWS, so we might see slight differences in the outcome.
</Warning>

1. In order to test your agent locally, you can add an `if __name__ == "__main__"` declaration in the end of the file as follows:

```python title="lambda_function.py" theme={"dark"}
# ... imports from before
@editor_agent()
def lambda_handler(frame_data: FrameData):
    print(frame_data.model_dump_json())
    
if __name__ == '__main__':
    event = {
        "body": {
            "projectHash": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "dataHash": "00000000-1111-2222-3333-444444444444",
            "frame": 0,
            "objectHashes": []
        }
    }
    lambda_handler(event, None)
```

2. Make sure to update the Project and data hash to correspond to one of your data units.

<Tip>
  If you open the label editor in your browser and look at the url, it has this pattern:

  ```
  https://app.encord.com/label_editor/{projectHash}/{dataHash}
  ```
</Tip>

3. Run the file:

```shell theme={"dark"}
source venv/bin/activate
export ENCORD_SSH_KEY_FILE='/path/to/your/private-key-file'
python lambda_function.py
```

### STEP 4: Create the ZIP file

1. Create the zip file by first zipping what is in the `package` directory:

```shell theme={"dark"}
cd package
zip -r ../package.zip .
cd ..
```

2. Add your lambda function to the zip file:

```shell theme={"dark"}
zip package.zip lambda_function.py
```

### STEP 5: Set up an execution role

Your Lambda function requires an execution role to define the permissions it needs to run.

1. Create the configuration file `trust-policy.json` to be uploaded to AWS.

```json title="trust-policy.json" theme={"dark"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

2. Create a role with the trust policy:

```shell theme={"dark"}
aws iam create-role \
    --role-name lambda-execute-encord-agents \
    --assume-role-policy-document file://trust-policy.json
```

It should output a JSON similar to the following. Make sure to take a note of the `Arn`.

```json theme={"dark"}
{
  "Role": {
    "Path": "/",
    "RoleName": "lambda-execute-encord-agents",
    "RoleId": "AROAQ7BEARV2DSFT2E3PI",
    "Arn": "arn:aws:iam::061234567890:role/lambda-execute-encord-agents",
    "CreateDate": "2025-05-09T10:39:35+00:00",
    "AssumeRolePolicyDocument": {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Service": "lambda.amazonaws.com"
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }
  }
}
```

4. Attach the basic lambda execution role to the role.

```shell theme={"dark"}
aws iam attach-role-policy \
    --role-name lambda-execute-encord-agents \
    --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
```

### STEP 6: Upload the zip

1. To upload the zip file to AWS, use the following command. Make sure to insert the `<lambda_function_name>` you want to use and the proper role `Arn` from STEP 5.

```shell theme={"dark"}
aws lambda create-function --function-name <lambda_function_name> \
  --runtime python3.12 \
  --handler lambda_function.lambda_handler \
  --role arn:aws:iam::061234567890:role/lambda-execute-encord-agents \
  --zip-file fileb://package.zip
```

<Tip>
  If you want to modify your lambda, follow the steps above again but call the update method rather than the `create-function` from the AWS CLI.

  ```shell theme={"dark"}
  aws lambda update-function-code \
      --function-name <lambda_function_name> \
      --zip-file fileb://package.zip
  ```
</Tip>

2. Proceed to [Step A](#step-a-configure-public-endpoint) below to complete the setup.

## Building a Lambda Function with Docker

The full AWS documentation for building docker images for lambda functions with Python is available [here](https://docs.aws.amazon.com/lambda/latest/dg/python-image.html).

### STEP 1: Create a Local Project

Start by creating a local project directory.

```shell theme={"dark"}
mkdir my_project
cd my_project
```

Then add a `requirements.txt` file.

```text title="requirements.txt" theme={"dark"}
boto3
encord-agents
```

#### (Optional) local environment

If you want, you can create a local environment for testing before building the docker image.

```
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### STEP 2: Define the Agent

1. Create a `lambda_function.py` file using the following template:

```python title="lambda_function.py" theme={"dark"}
from encord.objects.ontology_labels_impl import LabelRowV2

from encord_agents.core.data_model import FrameData
from encord_agents.aws import editor_agent


@editor_agent()
def lambda_handler(frame_data: FrameData, label_row: LabelRowV2) -> None:
    print(frame_data.model_dump_json())
    # label_row.save()
```

<Note>
  Make sure to name your file `lambda_function.py` and your function `lambda_handler` if you're following this example, as these names are referenced in the Docker image in [the next step](#step-3-build-the-docker-image).
</Note>

Complete the `lambda_handler` function with the logic you want to execute when the agent is triggered.

<Tip>
  For more Custom Agent examples, see the [examples section](/agents-documentation/Custom-Agents/Examples).
  You can inject multiple different [dependencies](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#Dependencies) into the function if necessary.
</Tip>

You can find multiple examples of what can be done with Custom Agents [here](/agents-documentation/Custom-Agents/Examples).

### STEP 3: Build the Docker Image

1. Create a `Dockerfile` with the following content.

```Dockerfile title="Dockerfile" theme={"dark"}
FROM public.ecr.aws/lambda/python:3.12

# Install the specified packages
COPY requirements.txt ${LAMBDA_TASK_ROOT}
RUN pip install -r requirements.txt

# Copy function code
COPY lambda_function.py ${LAMBDA_TASK_ROOT}

# Set the CMD to your handler 
# (could also be done as a parameter override outside of the Dockerfile)
CMD [ "lambda_function.lambda_handler" ]
```

2. Build the image locally.

<Note>
  You need to have `docker` and `buildx` installed.
</Note>

```shell theme={"dark"}
docker buildx build \
    --platform linux/amd64 \
    --provenance=false \
    -t encord-agents-my-agent-name:latest \
    .
```

### STEP 4: (Optional) Test the agent locally

To test the agent locally, you can spin up the container with the following command.

```shell theme={"dark"}
docker run \
    -e ENCORD_SSH_KEY="$(cat /path/to/your/private-key-file)" \
    -p 9000:8080 \
    --platform linux/amd64 \
    -t encord-agents-my-agent-name:latest
```

The respective lines ensures that we

* Add the `ENCORD_SSH_KEY` env variable
* Map the port 8080 to your own local port (9000 in this example)
* AWS architecture needs to be `amd64` (or `arm64` [see aws docs](https://docs.aws.amazon.com/lambda/latest/dg/python-image.html#python-image-clients))
* Run the latest built image (`encord-agents-example:latest` in this example)

You can "hit" the function endpoint with a `curl` command. The `functions/function/invocation` path is required by Amazon.

```shell theme={"dark"}
curl "http://localhost:9000/2015-03-31/functions/function/invocations" \
    -X "POST" \
    -d '{
            "body": {
                "projectHash": "aaaaaaaa-ed79-4a1b-a0c1-b1b38ffb523c",
                "dataHash":"659c3a38-737f-4f56-a709-26ce01f5fd0b",
                "frame": 0,
                "objectHashes": []
            }
        }'
```

<Note>
  There is a long-standing issue with Lambda Docker containers where the API differs between local and cloud execution. In this case, two relevant distinctions exist.

  * `Content-Type`: Locally, the container expects a post request with `Content-Type: application/x-www-form-urlencoded` while the public url hosted by AWS expects `Content-Type: application/application-json`.
  * `POST` data: Locally, the post data needs to be `{"body": {... content dict}}` while the public url expects `{... content dict}`.

  As a consequence, the equivalent `curl` request for a publicly hosted lambda function would be:

  ```
  curl "https://<your_function_url_prefix>.lambda-url.eu-west-1.on.aws/" \
      -X "POST" \
      -H "Content-Type: application/json" \
      -d '{
          "projectHash": "aaaaaaaa-ed79-4a1b-a0c1-b1b38ffb523c",
          "dataHash":"659c3a38-737f-4f56-a709-26ce01f5fd0b",
          "frame": 0,
          "objectHashes": []
      }'
  ```

  See [the Function URL section](#step-a-configure-public-endpoint) for more information on how to get the public endpoint.
</Note>

### Step 5: Prepare ECR Container Repository

To associate a Lambda function with your container, the container must first be uploaded to the AWS Elastic Container Registry (ECR). For this, a container repository is required.

1. Run the `aws get-login-password` command to authenticate the Docker CLI to your Amazon ECR registry.

* Set the `--region` value to the AWS Region where you want to create the Amazon ECR repository (we use `eu-west-1` in this example).
* Replace 111122223333 with your AWS account ID.

```shell theme={"dark"}
aws ecr get-login-password --region eu-west-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.eu-west-1.amazonaws.com
```

2. Create a repository in Amazon ECR using the create-repository command.

```shell theme={"dark"}
aws ecr create-repository \
    --repository-name <your-lambda-function-name> \
    --region us-east-1 \
    --image-scanning-configuration scanOnPush=true \
    --image-tag-mutability MUTABLE
```

If successful, you see a response with the following format:

```
{
    "repository": {
        "repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/<your-lambda-function-name>",
        "registryId": "111122223333",
        "repositoryName": "<your-lambda-function-name>",
        "repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/<your-lambda-function-name>",
        "createdAt": "2025-05-12T10:39:01+00:00",
        "imageTagMutability": "MUTABLE",
        "imageScanningConfiguration": {
            "scanOnPush": true
        },
        "encryptionConfiguration": {
            "encryptionType": "AES256"
        }
    }
}
```

Copy the `repositoryUri` from the output.

### Step 6: Upload the Local Docker Image

1. To tag your local Docker image for Amazon ECR as the latest version, use the `docker tag` command:

* `encord-agents-my-agent-name:latest` is the name and tag of your local Docker image. This is the image name and tag that you specified in the `docker build` command [above](#step-3-build-the-docker-image).
* Replace `<ecr-repository-uri>` with the `repositoryUri` that you copied [above](#step-5-prepare-ecr-container-repository). Make sure to include `:latest` at the end of the URI.

```shell theme={"dark"}
docker tag encord-agents-my-agent-name:latest <ecr-repository-uri>:latest
```

2. Run the `docker push` command to deploy your local image to the Amazon ECR repository. Ensure you include `:latest` at the end of the repository URI.

```shell theme={"dark"}
docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```

### STEP 7: Set up an Execution Role

Your Lambda function requires an execution role to define the permissions it needs to run.

1. Create the configuration file `trust-policy.json` to be uploaded to AWS.

```json title="trust-policy.json" theme={"dark"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

2. Create a role with the trust policy.

```shell theme={"dark"}
aws iam create-role \
    --role-name lambda-execute-encord-agents \
    --assume-role-policy-document file://trust-policy.json
```

It should output a JSON similar to the following. Make sure to take a note of the `Arn`.

```json theme={"dark"}
{
  "Role": {
    "Path": "/",
    "RoleName": "lambda-execute-encord-agents",
    "RoleId": "AROAQ7BEARV2DSFT2E3PI",
    "Arn": "arn:aws:iam::061234567890:role/lambda-execute-encord-agents",
    "CreateDate": "2025-05-09T10:39:35+00:00",
    "AssumeRolePolicyDocument": {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Service": "lambda.amazonaws.com"
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }
  }
}
```

3. Attach the basic lambda execution role to the role.

```shell theme={"dark"}
aws iam attach-role-policy \
    --role-name lambda-execute-encord-agents \
    --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
```

### STEP 8: Creating a Lambda Function

For `ImageUri`, specify the repository URI from [Step 5](#step-5-prepare-ecr-container-repository). Ensure you include `:latest` at the end of the URI.

```shell theme={"dark"}
aws lambda create-function \
  --function-name <my-function-name> \
  --package-type Image \
  --code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/<your-lambda-function-name>:latest \
  --role arn:aws:iam::061234567890:role/lambda-execute-encord-agents
```

<Tip>
  To update the container image, rebuild it (as in [Step 3](#step-3-build-the-docker-image)), then tag it with the repository URI and upload it again (as in [Step 6](#step-6-upload-the-local-docker-image)).

  Instead of the `create-function` call in the end, you do the following.

  ```shell theme={"dark"}
  aws lambda update-function-code \
      --function-name pdf-qa \
      --image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/<your-lambda-function-name>:latest \
      --publish
  ```

  The URL stays the same, so there is no need to reconfigure CORS or anything else.
</Tip>

Now, proceed to [Step A](#step-a-configure-public-endpoint) below to complete the setup.

## Communication with Encord

### STEP A: Configure Public Endpoint

Now the function is live but not publicly available to the internet.
To make it accessible to the Encord platform, follow these steps:

To make your live Lambda function publicly accessible to the Encord platform, follow these steps:

1. Go to [https://console.aws.amazon.com/lambda](https://console.aws.amazon.com/lambda) and navigate to your newly created function.
2. Go to the **Configuration** tab and choose the **Function URL** section.
3. Click the **Create function URL** button.
4. Choose `NONE` for **Auth type**.
5. Expand the **Additional settings** panel and check the **Configure cross-origin resource sharing (CORS)** box.
6. In the **Allow origin** section, add `https://app.encord.com`, `https://app.us.encord.com`, or your custom (VPC) domain.
7. Under the **Allow headers** section, add both `content-type` and `x-encord-editor-agent` values.
8. In the **Allow methods** section, choose `POST`.
9. Click **Save**.

The configuration should look similar to the following image (potentially with fewer allowed origins).

<Tip>
  You can click the image to expand it.
</Tip>

![AWS Function url configuration](https://storage.googleapis.com/docs-media.encord.com/assets/aws-function-url-configuration.png)

### STEP B: Adding Secrets

Your agent requires an access key secret. In the AWS console where you configured the function URL, click the **Environment variables** tab on the left. Add the `ENCORD_SSH_KEY` variable, along with any other necessary credentials (for example, HuggingFace, OpenAI, or Gemini).

<Tip>
  We recommend creating an Encord service account and using an associated access key. This ensures you provide only the necessary access permissions.
</Tip>

### STEP C: Associating the URL with Encord

Now that your AWS setup is complete, copy the Function URL displayed at the top of your AWS Lambda function's web page. Then, navigate to the Encord app.

1. Click the **Agents** section on the left. The **Agents catalog** tab opens.
2. Click **Create custom agent** on the **Custom agent** tile.

<div>
  <img />
</div>

3. Give the agent a meaningful name and description.
4. Paste the function URL into the **Agent endpoint** field.
5. Click **Create custom agent**.


# Custom Domain
Source: https://docs.encord.com/agents-documentation/Custom-Agents/Custom-Domain



***

## Custom Agent Configuration for US Domain or VPC

This section guides users operating Encord with the US domain (`https://api.us.encord.com`) or within their private Virtual Private Cloud (VPC) on how to configure their Custom Agents.

***

### STEP 1: Set the `ENCORD_DOMAIN` Environment Variable

Define the **Encord API domain**, not the front-end application domain.

* **Running Locally:**
  ```shell theme={"dark"}
  export ENCORD_DOMAIN=https://api.us.encord.com
  ```
* **Deploying with a GCP Cloud Function:** Create a GCP secret and pass in the domain:
  ```shell theme={"dark"}
  --set-secrets="ENCORD_SSH_KEY=YOUR_GCP_STORED_KEY:latest,ENCORD_DOMAIN=YOUR_GCP_STORED_DOMAIN"
  ```

***

### STEP 2: Set the `ENCORD_SSH_KEY` or `ENCORD_SSH_KEY_FILE` Environment Variables

Provide your access key for authentication.

* **Running Locally:**
  ```shell theme={"dark"}
  export ENCORD_SSH_KEY_FILE="path/to/your/key"
  ```
  or
  ```shell theme={"dark"}
  export ENCORD_SSH_KEY="<your key>"
  ```
* **Deploying with a GCP Cloud Function:** Create a GCP secret and pass in the key:
  ```shell theme={"dark"}
  --set-secrets="ENCORD_SSH_KEY=YOUR_GCP_STORED_KEY:latest,ENCORD_DOMAIN=YOUR_GCP_STORED_DOMAIN"
  ```

***

### STEP 3: Pass the Front-end Domain to the Custom Agent Declaration

Pass the **Encord front-end domain** into the `@editor_agent` declaration to ensure the function respects Cross-Origin Resource Sharing (CORS):

```python theme={"dark"}
@editor_agent(custom_cors_regex="https://app.us.encord.com") # Or the domain of your custom FE
```


# FastAPI Examples
Source: https://docs.encord.com/agents-documentation/Custom-Agents/Examples/FastAPI-Examples



## Basic Geometric Example

A simple example showing how to use objectHashes.

```python agent.py theme={"dark"}
from typing import Annotated

from encord.objects.ontology_labels_impl import LabelRowV2
from encord.objects.ontology_object_instance import ObjectInstance
from fastapi import Depends, FastAPI

from encord_agents.fastapi.cors import get_encord_app()
from encord_agents.fastapi.dependencies import (
    FrameData,
    dep_label_row,
    dep_objects,
)

# Initialize FastAPI app
app = get_encord_app()


@app.post("/handle-object-hashes")
def handle_object_hashes(
    frame_data: FrameData,
    lr: Annotated[LabelRowV2, Depends(dep_label_row)],
    object_instances: Annotated[list[ObjectInstance], Depends(dep_objects)],
) -> None:
    for object_inst in object_instances:
        print(object_inst)
```

**Use Case: Selective OCR on Selected Objects**

This functionality allows you to apply your own OCR model to specific objects selected directly within the Encord platform.

When you trigger your agent from the Encord app after selecting objects, the platform automatically sends a list of `objectHashes` to your agent. Your agent can then use the `dep_objects` method to gain immediate access to these specific object instances, which greatly simplifies integrating your OCR model for targeted processing.

**Test the Agent**

1. Save the above code as `agent.py`.
2. Run the following command to run the agent in debug mode in your terminal.

```shell theme={"dark"}
uvicorn main:app --reload --port 8080
```

3. Open your Project in the Encord platform and navigate to a frame with an object that you want to act on. Choose an object from the bottom left sider and click `Copy URL` as shown:

<div>
  <img alt="Copy URL from left sider" />
</div>

<Tip>
  The url should have roughly this format: `"https://app.encord.com/label_editor/{project_hash}/{data_hash}/{frame}/0?other_query_params&objectHash={objectHash}"`.
</Tip>

4. In another shell operating from the same working directory, source your virtual environment and test the agent.

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local agent '<your_url>'
```

5. To see if the test is successful, refresh your browser to see the action taken by the Agent. If the test has run successfully, the agent can be deployed. Visit [the deployment documentation](/agents-documentation/Custom-Agents/GCP-Cloud-Functions#step-4-deployment) to learn more.

## Nested Classification using Claude 3.5 Sonnet

The goals of this example is to:

1. Create a Custom Agent that can automatically fill in frame-level classifications in the Label Editor.
2. Demonstrate how to use the [`OntologyDataModel`](/agents-documentation/Reference/Core/Agents-Reference-Core#ontologydatamodel-objects) for classifications.
3. Demonstrate how to build an agent using FastAPI that can be self-hosted.

**Prerequisites**

Before you begin, ensure you have:

* Created a virtual Python environment.
* Installed all necessary dependencies.
* Have an [Anthropic API key](https://www.anthropic.com/api).
* Are able to [authenticate with Encord](/agents-documentation/Basics/Authentication).

Run the following commands to set up your environment:

```shell theme={"dark"}
python -m venv venv                   # Create a virtual Python environment  
source venv/bin/activate              # Activate the virtual environment 
python -m pip install "fastapi[standard]" encord-agents anthropic # Install required dependencies  
export ANTHROPIC_API_KEY="<your_api_key>" # Set your Anthropic API key 
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"  # Define your Encord access key 
```

**Project Setup**

Create a Project with visual content (images, image groups, image sequences, or videos) in Encord. This example uses the following Ontology, but any Ontology containing classifications can be used.

<div>
  <img />
</div>

<AccordionGroup>
  <Accordion title="Ontology JSON and Script">
    ```json Ontology JSON theme={"dark"}
    {
      "objects": [],
      "classifications": [
        {
          "id": "1",
          "featureNodeHash": "TTkHMtuD",
          "attributes": [
            {
              "id": "1.1",
              "featureNodeHash": "+1g9I9Sg",
              "type": "text",
              "name": "scene summary",
              "required": false,
              "dynamic": false
            }
          ]
        },
        {
          "id": "2",
          "featureNodeHash": "xGV/wCD0",
          "attributes": [
            {
              "id": "2.1",
              "featureNodeHash": "k3EVexk7",
              "type": "radio",
              "name": "is there a person in the frame?",
              "required": false,
              "options": [
                {
                  "id": "2.1.1",
                  "featureNodeHash": "EkGwhcO4",
                  "label": "yes",
                  "value": "yes",
                  "options": [
                    {
                      "id": "2.1.1.1",
                      "featureNodeHash": "mj9QCDY4",
                      "type": "text",
                      "name": "What is the person doing?",
                      "required": false
                    }
                  ]
                },
                {
                  "id": "2.1.2",
                  "featureNodeHash": "37rMLC/v",
                  "label": "no",
                  "value": "no",
                  "options": []
                }
              ],
              "dynamic": false
            }
          ]
        }
      ]
    }
    ```

    To construct the same Ontology as used in this example, run the following script.

    ```python Create Ontology theme={"dark"}
    import json
    from encord.objects.ontology_structure import OntologyStructure
    from encord_agents.core.utils import get_user_client

    encord_client = get_user_client()
    structure = OntologyStructure.from_dict(json.loads("{the_json_above}"))
    ontology = encord_client.create_ontology(
        title="Your ontology title",
        structure=structure
    )
    print(ontology.ontology_hash)
    ```
  </Accordion>
</AccordionGroup>

The aim is to trigger an agent that transforms a labeling task from Figure A to Figure B.

<img />

<strong>Figure A:</strong> No classification labels.

<img />

<strong>Figure B:</strong> Multiple nested classification labels generated by an LLM.

**Create the Agent**

This section provides the complete code for creating your Custom Agent, along with an explanation of its internal workings.

**Agent Setup Steps**

1. Import dependencies, authenticate with Encord, and set up the Project. Ensure you insert your Project's unique identifier.

2. Create a data model and a system prompt based on the Project Ontology to tell Claude how to structure its response.

3. Set up an Anthropic API client to establish communication with the Claude model.

4. Define the Custom Agent. This includes:

* Receiving frame data using FastAPI's Form dependency.
* Retrieving the associated label row and frame content using Encord Agents' dependencies.
* Constructing a Frame object from the content.
* Sending the frame image to Claude for analysis.
* Parsing Claude's response into classification instances.
* Adding these classifications to the label row and saving the updated data.

````python theme={"dark"}
# 1. Import dependencies and set up the Project. The CORS middleware is crucial as it allows the Encord platform to make requests to your API.
import os

import numpy as np
from anthropic import Anthropic
from encord.objects.ontology_labels_impl import LabelRowV2
from fastapi import Depends
from numpy.typing import NDArray
from typing_extensions import Annotated

from encord_agents.core.data_model import Frame
from encord_agents.core.ontology import OntologyDataModel
from encord_agents.core.utils import get_user_client
from encord_agents.fastapi.cors import get_encord_app
from encord_agents.fastapi.dependencies import (
    FrameData,
    dep_label_row,
    dep_single_frame,
)

# Initialize FastAPI app
app = get_encord_app()

# 2. Set up the Project and create a data model based on the Ontology.

client = get_user_client()
project = client.get_project("<your_project_hash>")
data_model = OntologyDataModel(project.ontology_structure.classifications)

# 3. Set up Claude and create the system prompt that tells Claude how to structure its response.
system_prompt = f"""
You're a helpful assistant that's supposed to help fill in json objects 
according to this schema:

    ```json
    {data_model.model_json_schema_str}
    ```

Please only respond with valid json.
"""

ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
anthropic_client = Anthropic(api_key=ANTHROPIC_API_KEY)

# 4. Define the Custom Agent
@app.post("/frame_classification")
async def classify_frame(
    frame_data: FrameData,
    lr: Annotated[LabelRowV2, Depends(dep_label_row)],
    content: Annotated[NDArray[np.uint8], Depends(dep_single_frame)],
):
    # Receives frame data using FastAPI's Form dependency.
    # Note: FastAPI handles parsing the incoming request body (which implicitly includes frame_data,
    # and the dependencies (dep_label_row, dep_single_frame) resolve the lr and content).

    """Classify a frame using Claude."""
    # Constructs a `Frame` object with the content.
    frame = Frame(frame=frame_data.frame, content=content) 
    
    # Sends the frame image to Claude for analysis.
    message = anthropic_client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        system=system_prompt,
        messages=[
            {
                "role": "user",
                "content": [frame.b64_encoding(output_format="anthropic")],
            }
        ],
    )
    try:
        # Parses Claude's response into classification instances.
        classifications = data_model(message.content[0].text) 
        for clf in classifications:
            clf.set_for_frames(frame_data.frame, confidence=0.5, manual_annotation=False)
            # Adds classifications to the label row
            lr.add_classification_instance(clf) 
    except Exception:
        import traceback

        traceback.print_exc()
        print(f"Response from model: {message.content[0].text}")

    # Saves the updated data.
    lr.save()
````

**Test the Agent**

1. In your current terminal run the following command to runFastAPI server in development mode with auto-reload enabled.

```shell theme={"dark"}
uvicorn main:app --reload --port 8080
```

2. Open your Project in the Encord platform and navigate to a frame you want to add a classification to. Copy the URL from your browser.

<Tip>
  The url should have the following format: `"https://app.encord.com/label_editor/{project_hash}/{data_hash}/{frame}"`
</Tip>

3. In another shell operating from the same working directory, source your virtual environment and test the agent.

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local frame_classification '<your_url>'
```

4. To see if the test is successful, refresh your browser to view the classifications generated by Claude. Once the test runs successfully, you are ready to deploy your agent. Visit the deployment documentation to learn more.

## Nested Attributes using Claude 3.5 Sonnet

The goals of this example are:

1. Create a Custom Agent that can convert generic object annotations (class-less coordinates) into class specific annotations with nested attributes like descriptions, radio buttons, and checklists.
2. Demonstrate how to use both the [`OntologyDataModel`](/agents-documentation/Reference/Core/Agents-Reference-Core#ontologydatamodel-objects) and the [`dep_object_crops`](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#dep-object-crops-2) dependency.

**Prerequisites**

Before you begin, ensure you have:

* Created a virtual Python environment.
* Installed all necessary dependencies.
* Have an [Anthropic API key](https://www.anthropic.com/api).
* Are able to [authenticate with Encord](/agents-documentation/Basics/Authentication).

Run the following commands to set up your environment:

```shell theme={"dark"}
python -m venv venv                 # Create a virtual Python environment  
source venv/bin/activate            # Activate the virtual environment  
python -m pip install encord-agents anthropic  # Install required dependencies  
export ANTHROPIC_API_KEY="<your_api_key>"     # Set your Anthropic API key  
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"  # Define your Encord access key  

```

**Project Setup**

Create a Project with visual content (images, image groups, image sequences, or videos) in Encord. This example uses the following Ontology, but any Ontology containing classifications can be used provided the object types are the same and there is one entry called "generic".

<div>
  <img />
</div>

<AccordionGroup>
  <Accordion title="Ontology JSON and Script">
    ```json ontology.json theme={"dark"}
    {
      "objects": [
        {
          "id": "1",
          "name": "person",
          "color": "#D33115",
          "shape": "bounding_box",
          "featureNodeHash": "2xlDPPAG",
          "required": false,
          "attributes": [
            {
              "id": "1.1",
              "featureNodeHash": "aFCN9MMm",
              "type": "text",
              "name": "activity",
              "required": false,
              "dynamic": false
            }
          ]
        },
        {
          "id": "2",
          "name": "animal",
          "color": "#E27300",
          "shape": "bounding_box",
          "featureNodeHash": "3y6JxTUX",
          "required": false,
          "attributes": [
            {
              "id": "2.1",
              "featureNodeHash": "2P7LTUZA",
              "type": "radio",
              "name": "type",
              "required": false,
              "options": [
                {
                  "id": "2.1.1",
                  "featureNodeHash": "gJvcEeLl",
                  "label": "dolphin",
                  "value": "dolphin",
                  "options": []
                },
                {
                  "id": "2.1.2",
                  "featureNodeHash": "CxrftGS4",
                  "label": "monkey",
                  "value": "monkey",
                  "options": []
                },
                {
                  "id": "2.1.3",
                  "featureNodeHash": "OQyWm7Sm",
                  "label": "dog",
                  "value": "dog",
                  "options": []
                },
                {
                  "id": "2.1.4",
                  "featureNodeHash": "CDKmYJK/",
                  "label": "cat",
                  "value": "cat",
                  "options": []
                }
              ],
              "dynamic": false
            },
            {
              "id": "2.2",
              "featureNodeHash": "5fFgrM+E",
              "type": "text",
              "name": "description",
              "required": false,
              "dynamic": false
            }
          ]
        },
        {
          "id": "3",
          "name": "vehicle",
          "color": "#16406C",
          "shape": "bounding_box",
          "featureNodeHash": "llw7qdWW",
          "required": false,
          "attributes": [
            {
              "id": "3.1",
              "featureNodeHash": "79mo1G7Q",
              "type": "text",
              "name": "type - short and concise",
              "required": false,
              "dynamic": false
            },
            {
              "id": "3.2",
              "featureNodeHash": "OFrk07Ds",
              "type": "checklist",
              "name": "visible",
              "required": false,
              "options": [
                {
                  "id": "3.2.1",
                  "featureNodeHash": "KmX/HjRT",
                  "label": "wheels",
                  "value": "wheels"
                },
                {
                  "id": "3.2.2",
                  "featureNodeHash": "H6qbEcdj",
                  "label": "frame",
                  "value": "frame"
                },
                {
                  "id": "3.2.3",
                  "featureNodeHash": "gZ9OucoQ",
                  "label": "chain",
                  "value": "chain"
                },
                {
                  "id": "3.2.4",
                  "featureNodeHash": "cit3aZSz",
                  "label": "head lights",
                  "value": "head_lights"
                },
                {
                  "id": "3.2.5",
                  "featureNodeHash": "qQ3PieJ/",
                  "label": "tail lights",
                  "value": "tail_lights"
                }
              ],
              "dynamic": false
            }
          ]
        },
        {
          "id": "4",
          "name": "generic",
          "color": "#FE9200",
          "shape": "bounding_box",
          "featureNodeHash": "jootTFfQ",
          "required": false,
          "attributes": []
        }
      ],
      "classifications": []
    }
    ```

    To construct the Ontology used in this example, run the following script:

    ```python theme={"dark"}
    import json
    from encord.objects.ontology_structure import OntologyStructure
    from encord_agents.core.utils import get_user_client

    encord_client = get_user_client()
    structure = OntologyStructure.from_dict(json.loads("{the_json_above}"))
    ontology = encord_client.create_ontology(
        title="Your ontology title",
        structure=structure
    )
    print(ontology.ontology_hash)
    ```
  </Accordion>
</AccordionGroup>

The goal is to trigger an agent that takes a labeling task from Figure A to Figure B, below:

<img />

<strong>Figure A:</strong> No classification labels.

<img />

<strong>Figure B:</strong> Multiple nested classification labels generated by an LLM.

**Create the Agent**

This section provides the complete code for creating your Custom Agent, along with an explanation of its internal workings.

**Agent Setup Steps**

1. Import Dependencies and Configure Project: Import necessary dependencies and set up your project. Remember to insert your project's unique identifier.

2. Create a data model and a system prompt based on the Project Ontology to tell Claude how to structure its response.

3. Initialize Anthropic API Client: Set up an API client to establish communication with the Claude model.

4. Define the Custom Agent:

* Arguments are automatically injected when the agent is called (see dependency injection details \[suspicious link removed]).
* The dep\_object\_crops dependency filters to include only "generic" object crops that still need classification.
* Call Claude with Image Crops: Use the crop.b64\_encoding method to send each image crop to Claude in a format it understands.

6. Parse Claude's Response and Update Labels: The data\_model parses Claude's JSON response, creating a new Encord object instance. If successful, the original generic object is replaced with the newly classified instance on the label row.

7. Save Labels.

```python theme={"dark"}
# 1. Import dependencies, authenticate with Encord, and set up the Project.
import os

from anthropic import Anthropic
from encord.objects.ontology_labels_impl import LabelRowV2
from fastapi import Depends
from typing_extensions import Annotated

from encord_agents.core.data_model import InstanceCrop
from encord_agents.core.ontology import OntologyDataModel
from encord_agents.core.utils import get_user_client
from encord_agents.fastapi.cors import get_encord_app
from encord_agents.fastapi.dependencies import (
    FrameData,
    dep_label_row,
    dep_object_crops,
)
# Initialize FastAPI app
app = get_encord_app()

# User client and ontology setup
client = get_user_client()
# Ensure you insert your Project's unique identifier.
project = client.get_project("<project_id>") 
generic_ont_obj, *other_objects = sorted(
    project.ontology_structure.objects,
    key=lambda o: o.title.lower() == "generic",
    reverse=True,
)

# 2. Create a data model and a system prompt based on the Project Ontology to tell Claude how to structure its response.
data_model = OntologyDataModel(other_objects)
system_prompt = f"""
You're a helpful assistant that's supposed to help fill in 
json objects according to this schema:

`{data_model.model_json_schema_str}`

Please only respond with valid json.
"""

# 3. Set up an Anthropic API client to establish communication with the Claude model.
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
anthropic_client = Anthropic(api_key=ANTHROPIC_API_KEY)


# 4. Define the Custom Agent.
@app.post("/object_classification")
async def classify_objects(
    frame_data: FrameData,
    lr: Annotated[LabelRowV2, Depends(dep_label_row)],
    crops: Annotated[
        list[InstanceCrop],
        Depends(dep_object_crops(filter_ontology_objects=[generic_ont_obj])),
    ],
):
    """Classify generic objects using Claude."""
    changes = False
    # Iterating through each object crop.
    for crop in crops:
        # 5. Call Claude with Image Crops.
        # Sending each crop image to Claude for analysis.
        message = anthropic_client.messages.create(
            model="claude-3-haiku-20240307",
            max_tokens=1024,
            system=system_prompt,
            messages=[
                {
                    "role": "user",
                    "content": [crop.b64_encoding(output_format="anthropic")],
                }
            ],
        )

        # 6. Parse Claude's Response and Update Labels.
        try:
            # Parsing Claude's response into an updated object instance.
            instance = data_model(message.content[0].text)

            coordinates = crop.instance.get_annotation(frame=frame_data.frame).coordinates
            instance.set_for_frames(
                coordinates=coordinates,
                frames=frame_data.frame,
                confidence=0.5,
                manual_annotation=False,
            )
            # Updating the label row by removing the original object and adding the newly classified instance.
            lr.remove_object(crop.instance) 
            lr.add_object_instance(instance)
            changes = True
        except Exception:
            import traceback

            traceback.print_exc()
            print(f"Response from model: {message.content[0].text}")

    # 7. Save Labels.
    if changes: 
        lr.save()
```

**Testing the Agent**

1. In your current terminal run the following command to runFastAPI server in development mode with auto-reload enabled.

```shell theme={"dark"}
fastapi dev agent.py --port 8080
```

2. Open your Project in the Encord platform and navigate to a frame you want to add a classification to. Copy the URL from your browser.

<Tip>
  The url should have roughly this format: `"https://app.encord.com/label_editor/{project_hash}/{data_hash}/{frame}"`.
</Tip>

3. In another shell operating from the same working directory, source your virtual environment and test the agent:

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local object_classification '<your_url>'
```

4. To see if the test is successful, refresh your browser to view the classifications generated by Claude. Once the test runs successfully, you are ready to deploy your agent. Visit the deployment documentation to learn more.

## Video Recaptioning using GPT-4o-mini

The goals of this example are:

1. Create a Custom Agent that automatically generates multiple variations of video captions.
2. Demonstrate how to use OpenAI's GPT-4o-mini model to enhance human-created video captions with a FastAPI-based agent.

**Prerequisites**

Before you begin, ensure you have:

* Created a virtual Python environment.
* Installed all necessary dependencies.
* Have an OpenAI API key.
* Are able to [authenticate with Encord](/agents-documentation/Basics/Authentication).

Run the following commands to set up your environment:

```shell theme={"dark"}
python -m venv venv                 # Create a virtual Python environment  
source venv/bin/activate            # Activate the virtual environment  
python -m pip install encord-agents langchain-openai "fastapi[standard]" openai  # Install required dependencies  
export OPENAI_API_KEY="<your-api-key>"     # Set your OpenAI API key  
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"  # Define your Encord access key  
```

**Project Setup**

Create a Project containing videos in Encord.

This example requires an Ontology with four text classifications:

* One text classification for human-created summaries of what is happening in the video.
* Three text classifications to be automatically filled by the LLM.

<img />

<strong>Ontology</strong>

<AccordionGroup>
  <Accordion title="Ontology JSON and Script">
    ```json theme={"dark"}
        {
          "objects": [],
          "classifications": [
            {
              "id": "1",
              "featureNodeHash": "GCH8VHIK",
              "attributes": [
                {
                  "id": "1.1",
                  "name": "Caption",
                  "type": "text",
                  "required": false,
                  "featureNodeHash": "Yg7xXEfC"
                }
              ]
            },
            {
              "id": "2",
              "featureNodeHash": "PwQAwYid",
              "attributes": [
                {
                  "id": "2.1",
                  "name": "Caption Rephrased 1",
                  "type": "text",
                  "required": false,
                  "featureNodeHash": "aQdXJwbG"
                }
              ]
            },
            {
              "id": "3",
              "featureNodeHash": "3a/aSnHO",
              "attributes": [
                {
                  "id": "3.1",
                  "name": "Caption Rephrased 2",
                  "type": "text",
                  "required": false,
                  "featureNodeHash": "8zY6H62x"
                }
              ]
            },
            {
              "id": "4",
              "featureNodeHash": "FNjXp5TU",
              "attributes": [
                {
                  "id": "4.1",
                  "name": "Caption Rephrased 3",
                  "type": "text",
                  "required": false,
                  "featureNodeHash": "sKg1Kq/m"
                }
              ]
            }
          ]
        }
    ```

    To construct the Ontology used in this example, run the following script:

    ```python theme={"dark"}
    import json
    from encord.objects.ontology_structure import OntologyStructure
    from encord.objects.attributes import TextAttribute

    structure = OntologyStructure()
    caption = structure.add_classification()
    caption.add_attribute(TextAttribute, "Caption")
    re1 = structure.add_classification()
    re1.add_attribute(TextAttribute, "Recaption 1")
    re2 = structure.add_classification()
    re2.add_attribute(TextAttribute, "Recaption 2")
    re3 = structure.add_classification()
    re3.add_attribute(TextAttribute, "Recaption 3")

    print(json.dumps(structure.to_dict(), indent=2))

    create_ontology = False
    if create_ontology:
        from encord.user_client import EncordUserClient
        client = EncordUserClient.create_with_ssh_private_key()  # Look in auth section for authentication
        client.create_ontology("title", "description", structure)
    ```
  </Accordion>
</AccordionGroup>

The workflow for this agent is:

1. A human watches the video and enters a caption in the first text field.

2. The agent is then triggered and generates three additional caption variations for review.

* Each video is first annotated by a human (ANNOTATE stage).
* Next, a data agent automatically generates alternative captions (AGENT stage).
* Finally, a human reviews all four captions (REVIEW stage) before the task is marked complete.

<Note>
  If no human caption is present when the agent is triggered, the task is sent back for annotation.
  If the review stage results in rejection, the task is also returned for re-annotation.
</Note>

<figure>
  <img />

  <strong>Workflow</strong>
</figure>

**Create the Agent**

This section provides the complete code for creating your Custom Agent, along with an explanation of its internal workings.

**Agent Setup Steps**

1. Set up imports and create a Pydantic model for our LLM's structured output

2. Create a detailed system prompt for the LLM that explains exactly what kind of rephrasing we want

3. We configure the LLM to use structured outputs based on our model

4. Create a helper function to prompt the model with both text and image:

5. Initialize the FastAPI app with the required CORS middleware:

6. Define the agent to handle the recaptioning. This includes:

* Retrieving the existing human-created caption, prioritizing captions from the current frame or falling back to frame zero.
* Sending the first frame of the video along with the human caption to the LLM.
* Processing the response from the LLM, which provides three alternative phrasings of the original caption.
* Updating the label row with the new captions, replacing any existing ones.

```python theme={"dark"}
# 1. Set up imports and create a Pydantic model for our LLM's structured output.
import os
from typing import Annotated

import numpy as np
from encord.exceptions import LabelRowError
from encord.objects.classification_instance import ClassificationInstance
from encord.objects.ontology_labels_impl import LabelRowV2
from fastapi import Depends
from langchain_openai import ChatOpenAI
from numpy.typing import NDArray
from pydantic import BaseModel

from encord_agents import FrameData
from encord_agents.fastapi.cors import get_encord_app
from encord_agents.fastapi.dependencies import Frame, dep_label_row, dep_single_frame

# The response model for the agent to follow.
class AgentCaptionResponse(BaseModel):
    rephrase_1: str
    rephrase_2: str
    rephrase_3: str


# 2. Create a detailed system prompt for the LLM that explains exactly what kind of rephrasing we want.
SYSTEM_PROMPT = """
You are a helpful assistant that rephrases captions.

I will provide you with a video caption and an image of the scene of the video. 

The captions follow this format:

"The droid picks up <cup_0> and puts it on the <table_0>."

The captions that you make should replace the tags, e.g., <cup_0>, with the actual object names.
The replacements should be consistent with the scene.

Here are three rephrases: 

1. The droid picks up the blue mug and puts it on the left side of the table.
2. The droid picks up the cup and puts it to the left of the plate.
3. The droid is picking up the mug on the right side of the table and putting it down next to the plate.

You will rephrase the caption in three different ways, as above, the rephrases should be

1. Diverse in terms of adjectives, object relations, and object positions.
2. Sound in relation to the scene. You cannot talk about objects you cannot see.
3. Short and concise. Keep it within one sentence.

"""

# 3. Configure the LLM to use structured outputs based on our model.
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.4, api_key=os.environ["OPENAI_API_KEY"])
llm_structured = llm.with_structured_output(AgentCaptionResponse)


# 4. Create a helper function to prompt the model with both text and image.
def prompt_gpt(caption: str, image: Frame) -> AgentCaptionResponse:
    prompt = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {
            "role": "user",
            "content": [
                {"type": "text", "text": f"Video caption: `{caption}`"},
                image.b64_encoding(output_format="openai"),
            ],
        },
    ]
    return llm_structured.invoke(prompt)


# 5. Initialize the FastAPI app with the required CORS middleware.
app = get_encord_app()


# 6. Define the agent to handle the recaptioning.
@app.post("/my_agent")
def my_agent(
    frame_data: FrameData,
    label_row: Annotated[LabelRowV2, Depends(dep_label_row)],
    frame_content: Annotated[NDArray[np.uint8], Depends(dep_single_frame)],
) -> None:
    # Get the relevant Ontology information
    # Recall that we expect
    # [human annotation, llm recaption 1, llm recaption 2, llm recaption 3]
    # in the Ontology
    cap, *rs = label_row.ontology_structure.classifications

    # Retrieve the existing human-created caption, prioritizing captions from the current frame or falling back to frame zero.
    instances = label_row.get_classification_instances(
        filter_ontology_classification=cap, filter_frames=[0, frame_data.frame]
    )
    if not instances:
        # nothing to do if there are no human labels
        return
    elif len(instances) > 1:

        def order_by_current_frame_else_frame_0(
            instance: ClassificationInstance,
        ) -> bool:
            try:
                instance.get_annotation(frame_data.frame)
                return 2  # The best option
            except LabelRowError:
                pass
            try:
                instance.get_annotation(0)
                return 1
            except LabelRowError:
                return 0

        instance = sorted(instances, key=order_by_current_frame_else_frame_0)[-1]
    else:
        instance = instances[0]

    # Read the actual string caption
    caption = instance.get_answer()

    # Send the first frame of the video along with the human caption to the LLM.
    frame = Frame(frame=0, content=frame_content)
    response = prompt_gpt(caption, frame)

    # Process the LLM's response, which contains three different versions of the original caption.
    # Update the label row with the new captions, replacing any existing ones.
    for r, t in zip(rs, [response.rephrase_1, response.rephrase_2, response.rephrase_3]):
        # Overwrite any existing re-captions
        existing_instances = label_row.get_classification_instances(filter_ontology_classification=r)
        for existing_instance in existing_instances:
            label_row.remove_classification(existing_instance)

        # Create new instances
        ins = r.create_instance()
        ins.set_answer(t, attribute=r.attributes[0])
        ins.set_for_frames(0)
        label_row.add_classification_instance(ins)

    label_row.save()
```

**Test the Agent**

1. In your current terminal, run the following command to run the FastAPI server:

```shell theme={"dark"}
ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
OPENAI_API_KEY=<your-api-key> \
fastapi dev main.py
```

2. Open your Project in the Encord platform, navigate to a video frame, and add your initial caption. Copy the URL from your browser.

3. In another shell operating from the same working directory, source your virtual environment and test the agent:

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local my_agent '<your_url>'
```

4. Refresh your browser to view the three AI-generated caption variations. Once the test runs successfully, you are ready to deploy your agent. Visit [the deployment documentation](/agents-documentation/Custom-Agents/GCP-Cloud-Functions#step-4-deployment) to learn more.


# GCP Examples
Source: https://docs.encord.com/agents-documentation/Custom-Agents/Examples/GCP-Examples



## Basic Geometric Example

A simple example showing how to use objectHashes.

```python agent.py theme={"dark"}

from typing import Annotated

from encord.objects.ontology_labels_impl import LabelRowV2
from encord.objects.ontology_object_instance import ObjectInstance

from encord_agents.core.data_model import FrameData
from encord_agents.core.dependencies import Depends
from encord_agents.gcp.dependencies import dep_objects
from encord_agents.gcp.wrappers import editor_agent


@editor_agent()
def handle_object_hashes(
    frame_data: FrameData,
    lr: LabelRowV2,
    object_instances: Annotated[list[ObjectInstance], Depends(dep_objects)],
) -> None:
    for object_inst in object_instances:
        print(object_inst)

```

**Use Case: Selective OCR on Selected Objects**

This functionality allows you to apply your own OCR model to specific objects selected directly within the Encord platform.

When you trigger your agent from the Encord app after selecting objects, the platform automatically sends a list of `objectHashes` to your agent. Your agent can then use the `dep_objects` method to gain immediate access to these specific object instances, which greatly simplifies integrating your OCR model for targeted processing.

**Test the Agent**

1. Save the above code as `agent.py`.
2. Run the following command to run the agent in debug mode in your terminal.

```shell theme={"dark"}
functions-framework --target=handle_object_hashes --debug --source agent.py
```

3. Open your Project in the Encord platform and navigate to a frame with an object that you want to act on. Choose an object from the bottom left sider and click `Copy URL` as shown:

<div>
  <img alt="Copy URL from left sider" />
</div>

<Tip>
  The url should have roughly this format: `"https://app.encord.com/label_editor/{project_hash}/{data_hash}/{frame}/0?other_query_params&objectHash={objectHash}"`.
</Tip>

4. In another shell operating from the same working directory, source your virtual environment and test the agent.

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local agent '<your_url>'
```

5. To see if the test is successful, refresh your browser to see the action taken by the Agent. If the test has run successfully, the agent can be deployed. Visit [the deployment documentation](/agents-documentation/Custom-Agents/GCP-Cloud-Functions#step-4-deployment) to learn more.

## Nested Classification using Claude 3.5 Sonnet

The goals of this example are:

1. Create a Custom Agent that automatically adds frame-level classifications.
2. Demonstrate how to use the [`OntologyDataModel`](/agents-documentation/Reference/Core/Agents-Reference-Core#ontologydatamodel-objects) for classifications.

**Prerequisites**

Before you begin, ensure you have:

* Created a virtual Python environment.
* Installed all necessary dependencies.
* Have an [Anthropic API key](https://www.anthropic.com/api).
* Are able to [authenticate with Encord](/agents-documentation/Basics/Authentication).

Run the following commands to set up your environment:

```shell theme={"dark"}
python -m venv venv                 # Create a virtual Python environment  
source venv/bin/activate            # Activate the virtual environment  
python -m pip install encord-agents anthropic  # Install required dependencies  
export ANTHROPIC_API_KEY="<your_api_key>"     # Set your Anthropic API key  
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"  # Define your Encord access key  

```

**Project Setup**

Create a Project with visual content (images, image groups, image sequences, or videos) in Encord. This example uses the following Ontology, but any Ontology containing classifications can be used.

<div>
  <img />
</div>

<AccordionGroup>
  <Accordion title="Ontology JSON and Script">
    ```json Ontology JSON theme={"dark"}
    {
      "objects": [],
      "classifications": [
        {
          "id": "1",
          "featureNodeHash": "TTkHMtuD",
          "attributes": [
            {
              "id": "1.1",
              "featureNodeHash": "+1g9I9Sg",
              "type": "text",
              "name": "scene summary",
              "required": false,
              "dynamic": false
            }
          ]
        },
        {
          "id": "2",
          "featureNodeHash": "xGV/wCD0",
          "attributes": [
            {
              "id": "2.1",
              "featureNodeHash": "k3EVexk7",
              "type": "radio",
              "name": "is there a person in the frame?",
              "required": false,
              "options": [
                {
                  "id": "2.1.1",
                  "featureNodeHash": "EkGwhcO4",
                  "label": "yes",
                  "value": "yes",
                  "options": [
                    {
                      "id": "2.1.1.1",
                      "featureNodeHash": "mj9QCDY4",
                      "type": "text",
                      "name": "What is the person doing?",
                      "required": false
                    }
                  ]
                },
                {
                  "id": "2.1.2",
                  "featureNodeHash": "37rMLC/v",
                  "label": "no",
                  "value": "no",
                  "options": []
                }
              ],
              "dynamic": false
            }
          ]
        }
      ]
    }
    ```

    To construct the same Ontology as used in this example, run the following script.

    ```python Create Ontology theme={"dark"}
    import json
    from encord.objects.ontology_structure import OntologyStructure
    from encord_agents.core.utils import get_user_client

    encord_client = get_user_client()
    structure = OntologyStructure.from_dict(json.loads("{the_json_above}"))
    ontology = encord_client.create_ontology(
        title="Your ontology title",
        structure=structure
    )
    print(ontology.ontology_hash)
    ```
  </Accordion>
</AccordionGroup>

The aim is to trigger an agent that transforms a labeling task from Figure A to Figure B.

<img />

**Figure A: No classification labels.**

<img />

**Figure B: Multiple nested classification labels generated by an LLM.**

**Create the Agent**

This section provides the complete code for creating your Custom Agent, along with an explanation of its internal workings.

**Agent Setup Steps**

1. Import dependencies, authenticate with Encord, and set up the Project. Ensure you insert your Project's unique identifier.

2. Create a data model and a system prompt based on the Project Ontology to tell Claude how to structure its response.

3. Set up an Anthropic API client to establish communication with the Claude model.

4. Define the Custom Agent. This includes

* Retrieving Frame Content: It automatically fetches the current frame's image data using the `dep_single_frame` dependency.
* Analyzing with Claude: The frame image is then sent to the Claude AI model for analysis.
* Parsing Classifications: Claude's response is parsed and transformed into structured classification instances using the predefined data model.
* Saving Results: The new classifications are added to the active label row, and the updated results are saved within the Project.

````python theme={"dark"}
# 1. Import dependencies, authenticate with Encord, and set up the Project. Ensure you insert your Project's unique identifier.
import os

from anthropic import Anthropic
from encord.objects.ontology_labels_impl import LabelRowV2
from numpy.typing import NDArray
from typing_extensions import Annotated

from encord_agents.core.ontology import OntologyDataModel
from encord_agents.core.utils import get_user_client
from encord_agents.core.video import Frame
from encord_agents.gcp import Depends, editor_agent
from encord_agents.gcp.dependencies import FrameData, dep_single_frame

client = get_user_client()
project = client.get_project("<your_project_hash>")

# 2. Create a data model and a system prompt based on the Project Ontology to tell Claude how to structure its response
data_model = OntologyDataModel(project.ontology_structure.classifications)

system_prompt = f"""
You're a helpful assistant that's supposed to help fill in json objects 
according to this schema:

    ```json
    {data_model.model_json_schema_str}
    ```

Please only respond with valid json.
"""

# 3. Set up an Anthropic API client to establish communication with Claude 
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
anthropic_client = Anthropic(api_key=ANTHROPIC_API_KEY)

# 4. Define the Custom Agent
@editor_agent()
def agent(
    frame_data: FrameData,
    lr: LabelRowV2,
    content: Annotated[NDArray, Depends(dep_single_frame)],
):
    # # Retrieving Frame Content: It automatically fetches the current frame's image data using the `dep_single_frame` dependency
    frame = Frame(frame_data.frame, content=content)
    # Analyzing with Claude: The frame image is then sent to the Claude AI model for analysis
    message = anthropic_client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        system=system_prompt,
        messages=[
            {
                "role": "user",
                "content": [frame.b64_encoding(output_format="anthropic")],
            }
        ],
    )
    try:
        # Parsing Classifications: Claude's response is parsed and transformed into structured classification instances using the predefined data model
        classifications = data_model(message.content[0].text)
        for clf in classifications:
            clf.set_for_frames(frame_data.frame, confidence=0.5, manual_annotation=False)
            lr.add_classification_instance(clf)
    except Exception:
        import traceback

        traceback.print_exc()
        print(f"Response from model: {message.content[0].text}")
        
    # Saving Results: The new classifications are added to the active label row, and the updated results are saved within the Project.
    lr.save()

````

<AccordionGroup>
  <Accordion title="See the contents of data_model.model_json_schema_str here">
    ```json theme={"dark"}
    {
      "$defs": {
        "IsThereAPersonInTheFrameRadioModel": {
          "properties": {
            "feature_node_hash": {
              "const": "k3EVexk7",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "k3EVexk7"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "choice": {
              "description": "Choose exactly one answer from the given options.",
              "discriminator": {
                "mapping": {
                  "37rMLC/v": "#/$defs/NoNestedRadioModel",
                  "EkGwhcO4": "#/$defs/YesNestedRadioModel"
                },
                "propertyName": "feature_node_hash"
              },
              "oneOf": [
                {
                  "$ref": "#/$defs/YesNestedRadioModel"
                },
                {
                  "$ref": "#/$defs/NoNestedRadioModel"
                }
              ],
              "title": "Choice"
            }
          },
          "required": [
            "feature_node_hash",
            "choice"
          ],
          "title": "IsThereAPersonInTheFrameRadioModel",
          "type": "object"
        },
        "NoNestedRadioModel": {
          "properties": {
            "feature_node_hash": {
              "const": "37rMLC/v",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "37rMLC/v"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "title": {
              "const": "no",
              "default": "Constant value - should be included as-is.",
              "enum": [
                "no"
              ],
              "title": "Title",
              "type": "string"
            }
          },
          "required": [
            "feature_node_hash"
          ],
          "title": "NoNestedRadioModel",
          "type": "object"
        },
        "SceneSummaryTextModel": {
          "properties": {
            "feature_node_hash": {
              "const": "+1g9I9Sg",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "+1g9I9Sg"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "value": {
              "description": "Please describe the image as accurate as possible focusing on 'scene summary'",
              "maxLength": 1000,
              "minLength": 0,
              "title": "Value",
              "type": "string"
            }
          },
          "required": [
            "feature_node_hash",
            "value"
          ],
          "title": "SceneSummaryTextModel",
          "type": "object"
        },
        "WhatIsThePersonDoingTextModel": {
          "properties": {
            "feature_node_hash": {
              "const": "mj9QCDY4",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "mj9QCDY4"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "value": {
              "description": "Please describe the image as accurate as possible focusing on 'What is the person doing?'",
              "maxLength": 1000,
              "minLength": 0,
              "title": "Value",
              "type": "string"
            }
          },
          "required": [
            "feature_node_hash",
            "value"
          ],
          "title": "WhatIsThePersonDoingTextModel",
          "type": "object"
        },
        "YesNestedRadioModel": {
          "properties": {
            "feature_node_hash": {
              "const": "EkGwhcO4",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "EkGwhcO4"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "what_is_the_person_doing": {
              "$ref": "#/$defs/WhatIsThePersonDoingTextModel",
              "description": "A text attribute with carefully crafted text to describe the property."
            }
          },
          "required": [
            "feature_node_hash",
            "what_is_the_person_doing"
          ],
          "title": "YesNestedRadioModel",
          "type": "object"
        }
      },
      "properties": {
        "scene_summary": {
          "$ref": "#/$defs/SceneSummaryTextModel",
          "description": "A text attribute with carefully crafted text to describe the property."
        },
        "is_there_a_person_in_the_frame": {
          "$ref": "#/$defs/IsThereAPersonInTheFrameRadioModel",
          "description": "A mutually exclusive radio attribute to choose exactly one option that best matches to the give visual input."
        }
      },
      "required": [
        "scene_summary",
        "is_there_a_person_in_the_frame"
      ],
      "title": "ClassificationModel",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

**Test the Agent**

1. In your current terminal, run the following command to run the agent in debug mode.

```shell theme={"dark"}
functions-framework --target=agent --debug --source agent.py
```

2. Open your Project in [the Encord platform](https://app.encord.com/projects) and navigate to a frame you want to add a classification to. Copy the URL from your browser.

<Tip>
  The url should have the following format: `"https://app.encord.com/label_editor/{project_hash}/{data_hash}/{frame}"`.
</Tip>

3. In another shell operating from the same working directory, source your virtual environment and test the agent.

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local agent '<your_url>'
```

4. To see if the test is successful, refresh your browser to view the classifications generated by Claude. Once the test runs successfully, you are ready to deploy your agent. Visit [the deployment documentation](/agents-documentation/Custom-Agents/GCP-Cloud-Functions#step-4-deployment) to learn more.

## Nested Attributes using Claude 3.5 Sonnet

The goals of this example are:

1. Create a Custom Agent that can convert generic object annotations (class-less coordinates) into class specific annotations with nested attributes like descriptions, radio buttons, and checklists.

2. Demonstrate how to use both the [`OntologyDataModel`](/agents-documentation/Reference/Core/Agents-Reference-Core#ontologydatamodel-objects) and the [`dep_object_crops`](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents) dependency.

**Prerequisites**

Before you begin, ensure you have:

* Created a virtual Python environment.
* Installed all necessary dependencies.
* Have an [Anthropic API key](https://www.anthropic.com/api).
* Are able to [authenticate with Encord](/agents-documentation/Basics/Authentication).

Run the following commands to set up your environment:

```shell theme={"dark"}
python -m venv venv                 # Create a virtual Python environment  
source venv/bin/activate            # Activate the virtual environment  
python -m pip install encord-agents anthropic  # Install required dependencies  
export ANTHROPIC_API_KEY="<your_api_key>"     # Set your Anthropic API key  
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"  # Define your Encord access key  

```

**Project Setup**

Create a Project with visual content (images, image groups, image sequences, or videos) in Encord. This example uses the following Ontology, but any Ontology containing classifications can be used provided the object types are the same and there is one entry called `"generic"`.

<div>
  <img />
</div>

<AccordionGroup>
  <Accordion title="Ontology JSON and Script">
    ```json ontology.json theme={"dark"}
    {
      "objects": [
        {
          "id": "1",
          "name": "person",
          "color": "#D33115",
          "shape": "bounding_box",
          "featureNodeHash": "2xlDPPAG",
          "required": false,
          "attributes": [
            {
              "id": "1.1",
              "featureNodeHash": "aFCN9MMm",
              "type": "text",
              "name": "activity",
              "required": false,
              "dynamic": false
            }
          ]
        },
        {
          "id": "2",
          "name": "animal",
          "color": "#E27300",
          "shape": "bounding_box",
          "featureNodeHash": "3y6JxTUX",
          "required": false,
          "attributes": [
            {
              "id": "2.1",
              "featureNodeHash": "2P7LTUZA",
              "type": "radio",
              "name": "type",
              "required": false,
              "options": [
                {
                  "id": "2.1.1",
                  "featureNodeHash": "gJvcEeLl",
                  "label": "dolphin",
                  "value": "dolphin",
                  "options": []
                },
                {
                  "id": "2.1.2",
                  "featureNodeHash": "CxrftGS4",
                  "label": "monkey",
                  "value": "monkey",
                  "options": []
                },
                {
                  "id": "2.1.3",
                  "featureNodeHash": "OQyWm7Sm",
                  "label": "dog",
                  "value": "dog",
                  "options": []
                },
                {
                  "id": "2.1.4",
                  "featureNodeHash": "CDKmYJK/",
                  "label": "cat",
                  "value": "cat",
                  "options": []
                }
              ],
              "dynamic": false
            },
            {
              "id": "2.2",
              "featureNodeHash": "5fFgrM+E",
              "type": "text",
              "name": "description",
              "required": false,
              "dynamic": false
            }
          ]
        },
        {
          "id": "3",
          "name": "vehicle",
          "color": "#16406C",
          "shape": "bounding_box",
          "featureNodeHash": "llw7qdWW",
          "required": false,
          "attributes": [
            {
              "id": "3.1",
              "featureNodeHash": "79mo1G7Q",
              "type": "text",
              "name": "type - short and concise",
              "required": false,
              "dynamic": false
            },
            {
              "id": "3.2",
              "featureNodeHash": "OFrk07Ds",
              "type": "checklist",
              "name": "visible",
              "required": false,
              "options": [
                {
                  "id": "3.2.1",
                  "featureNodeHash": "KmX/HjRT",
                  "label": "wheels",
                  "value": "wheels"
                },
                {
                  "id": "3.2.2",
                  "featureNodeHash": "H6qbEcdj",
                  "label": "frame",
                  "value": "frame"
                },
                {
                  "id": "3.2.3",
                  "featureNodeHash": "gZ9OucoQ",
                  "label": "chain",
                  "value": "chain"
                },
                {
                  "id": "3.2.4",
                  "featureNodeHash": "cit3aZSz",
                  "label": "head lights",
                  "value": "head_lights"
                },
                {
                  "id": "3.2.5",
                  "featureNodeHash": "qQ3PieJ/",
                  "label": "tail lights",
                  "value": "tail_lights"
                }
              ],
              "dynamic": false
            }
          ]
        },
        {
          "id": "4",
          "name": "generic",
          "color": "#FE9200",
          "shape": "bounding_box",
          "featureNodeHash": "jootTFfQ",
          "required": false,
          "attributes": []
        }
      ],
      "classifications": []
    }
    ```

    To construct the Ontology used in this example, run the following script:

    ```python theme={"dark"}
    import json
    from encord.objects.ontology_structure import OntologyStructure
    from encord_agents.core.utils import get_user_client

    encord_client = get_user_client()
    structure = OntologyStructure.from_dict(json.loads("{the_json_above}"))
    ontology = encord_client.create_ontology(
        title="Your ontology title",
        structure=structure
    )
    print(ontology.ontology_hash)
    ```
  </Accordion>
</AccordionGroup>

The goal is create an agent that takes a labeling task from Figure A to Figure B

<img />

**Figure A: No classification labels.**

<img />

**Figure B: Multiple nested classification labels generated by an LLM.**

**Create the Agent**

This section provides the complete code for creating your Custom Agent, along with an explanation of its internal workings.

**Agent Setup Steps**

1. Import dependencies, authenticate with Encord, and set up the Project. Ensure you insert your Project's unique identifier.

2. Extract the generic Ontology object and the specific objects of interest. This example sorts Ontology objects based on whether their title is `"generic"`. The generic object is used to query image crops within the agent. Before that, `other_objects` is used to pass in the specific context we want Claude to focus on. The [`OntologyDataModel`](/agents-documentation/Reference/Core/Agents-Reference-Core#encord_agents.core.ontology.OntologyDataModel-Objects) class helps convert Encord Ontology [Objects](/sdk-documentation/sdk-references/objects.ontology_object) into a [Pydantic](https://docs.pydantic.dev/latest/) model and parse JSON into Encord [ObjectInstance](/sdk-documentation/sdk-references/objects.ontology_object_instance)s.

3. Prepare the system prompt for each object crop using the `data_model` to generate the JSON schema. Only `other_objects` is passed to ensure the model can choose only from non-generic object types.

4. Set up an Anthropic API client to establish communication with the Claude model. You must include your Anthropic API key.

5. Define the Custom Agent.

* All arguments are automatically injected when the agent is called. For details on dependency injection, see [here](/agents-documentation/Basics/Dependencies).
* The [`dep_object_crops`](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#dep-object-crops-2) dependency allows filtering. In this case, it includes only "generic" object crops, excluding those already converted to actual labels.

6. Query Claude using the image crops. The `crop` variable has a convenient `b64_encoding` method to produce an input that Claude understands.

7. Parse Claude's message using the `data_model`. When called with a JSON string, it attempts to parse it with respect to the JSON schema we saw above to create an Encord object instance. If successful, the old generic object can be removed and the newly classified object added.

8. Save the labels with Encord.

```python theme={"dark"}
# 1. Import dependencies, authenticate with Encord, and set up the Project. Ensure you insert your Project's unique identifier
import os

from anthropic import Anthropic
from encord.objects.ontology_labels_impl import LabelRowV2
from typing_extensions import Annotated

from encord_agents.core.ontology import OntologyDataModel
from encord_agents.core.utils import get_user_client
from encord_agents.gcp import Depends, editor_agent
from encord_agents.gcp.dependencies import FrameData, InstanceCrop, dep_object_crops

# User client
client = get_user_client()
project = client.get_project("<project_hash>")

# 2. Extract the generic Ontology object and the specific objects of interest. This example sorts Ontology objects based on whether their title is `"generic"`
generic_ont_obj, *other_objects = sorted(
    project.ontology_structure.objects,
    key=lambda o: o.title.lower() == "generic",
    reverse=True,
)

# 3. Prepare the system prompt for each object crop using the `data_model` to generate the JSON schema
data_model = OntologyDataModel(other_objects)
system_prompt = f"""
You're a helpful assistant that's supposed to help fill in 
json objects according to this schema:

`{data_model.model_json_schema_str}`

Please only respond with valid json.
"""

# 4. Set up an Anthropic API client to establish communication with the Claude model. You must include your Anthropic API key

ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
anthropic_client = Anthropic(api_key=ANTHROPIC_API_KEY)


# 5. Define the Custom Agent
@editor_agent()
def agent(
    frame_data: FrameData,
    lr: LabelRowV2,
    crops: Annotated[
        list[InstanceCrop],
        Depends(dep_object_crops(filter_ontology_objects=[generic_ont_obj])),
    ],
):
    # 6. Query Claude using the image crops. The `crop` variable has a convenient `b64_encoding` method to produce an input that Claude understands.
    changes = False
    for crop in crops:
        message = anthropic_client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=1024,
            system=system_prompt,
            messages=[
                {
                    "role": "user",
                    "content": [crop.b64_encoding(output_format="anthropic")],
                }
            ],
        )

        # 7. Parse Claude's message using the `data_model`.
        try:
            instance = data_model(message.content[0].text)

            coordinates = crop.instance.get_annotation(frame=frame_data.frame).coordinates
            instance.set_for_frames(
                coordinates=coordinates,
                frames=frame_data.frame,
                confidence=0.5,
                manual_annotation=False,
            )
            lr.remove_object(crop.instance)
            lr.add_object_instance(instance)
            changes = True
        except Exception:
            import traceback

            traceback.print_exc()
            print(f"Response from model: {message.content[0].text}")

    # 8. Save the labels with Encord.
    if changes:
        lr.save()

```

<AccordionGroup>
  <Accordion title="See the result of `data_model.model_json_schema_str` for the given example">
    ```json theme={"dark"}
    {
      "$defs": {
        "ActivityTextModel": {
          "properties": {
            "feature_node_hash": {
              "const": "aFCN9MMm",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "aFCN9MMm"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "value": {
              "description": "Please describe the image as accurate as possible focusing on 'activity'",
              "maxLength": 1000,
              "minLength": 0,
              "title": "Value",
              "type": "string"
            }
          },
          "required": [
            "feature_node_hash",
            "value"
          ],
          "title": "ActivityTextModel",
          "type": "object"
        },
        "AnimalNestedModel": {
          "properties": {
            "feature_node_hash": {
              "const": "3y6JxTUX",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "3y6JxTUX"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "type": {
              "$ref": "#/$defs/TypeRadioModel",
              "description": "A mutually exclusive radio attribute to choose exactly one option that best matches to the give visual input."
            },
            "description": {
              "$ref": "#/$defs/DescriptionTextModel",
              "description": "A text attribute with carefully crafted text to describe the property."
            }
          },
          "required": [
            "feature_node_hash",
            "type",
            "description"
          ],
          "title": "AnimalNestedModel",
          "type": "object"
        },
        "DescriptionTextModel": {
          "properties": {
            "feature_node_hash": {
              "const": "5fFgrM+E",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "5fFgrM+E"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "value": {
              "description": "Please describe the image as accurate as possible focusing on 'description'",
              "maxLength": 1000,
              "minLength": 0,
              "title": "Value",
              "type": "string"
            }
          },
          "required": [
            "feature_node_hash",
            "value"
          ],
          "title": "DescriptionTextModel",
          "type": "object"
        },
        "PersonNestedModel": {
          "properties": {
            "feature_node_hash": {
              "const": "2xlDPPAG",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "2xlDPPAG"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "activity": {
              "$ref": "#/$defs/ActivityTextModel",
              "description": "A text attribute with carefully crafted text to describe the property."
            }
          },
          "required": [
            "feature_node_hash",
            "activity"
          ],
          "title": "PersonNestedModel",
          "type": "object"
        },
        "TypeRadioEnum": {
          "enum": [
            "dolphin",
            "monkey",
            "dog",
            "cat"
          ],
          "title": "TypeRadioEnum",
          "type": "string"
        },
        "TypeRadioModel": {
          "properties": {
            "feature_node_hash": {
              "const": "2P7LTUZA",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "2P7LTUZA"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "choice": {
              "$ref": "#/$defs/TypeRadioEnum",
              "description": "Choose exactly one answer from the given options."
            }
          },
          "required": [
            "feature_node_hash",
            "choice"
          ],
          "title": "TypeRadioModel",
          "type": "object"
        },
        "TypeShortAndConciseTextModel": {
          "properties": {
            "feature_node_hash": {
              "const": "79mo1G7Q",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "79mo1G7Q"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "value": {
              "description": "Please describe the image as accurate as possible focusing on 'type - short and concise'",
              "maxLength": 1000,
              "minLength": 0,
              "title": "Value",
              "type": "string"
            }
          },
          "required": [
            "feature_node_hash",
            "value"
          ],
          "title": "TypeShortAndConciseTextModel",
          "type": "object"
        },
        "VehicleNestedModel": {
          "properties": {
            "feature_node_hash": {
              "const": "llw7qdWW",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "llw7qdWW"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "type__short_and_concise": {
              "$ref": "#/$defs/TypeShortAndConciseTextModel",
              "description": "A text attribute with carefully crafted text to describe the property."
            },
            "visible": {
              "$ref": "#/$defs/VisibleChecklistModel",
              "description": "A collection of boolean values indicating which concepts are applicable according to the image content."
            }
          },
          "required": [
            "feature_node_hash",
            "type__short_and_concise",
            "visible"
          ],
          "title": "VehicleNestedModel",
          "type": "object"
        },
        "VisibleChecklistModel": {
          "properties": {
            "feature_node_hash": {
              "const": "OFrk07Ds",
              "description": "UUID for discrimination. Must be included in json as is.",
              "enum": [
                "OFrk07Ds"
              ],
              "title": "Feature Node Hash",
              "type": "string"
            },
            "wheels": {
              "description": "Is 'wheels' applicable or not?",
              "title": "Wheels",
              "type": "boolean"
            },
            "frame": {
              "description": "Is 'frame' applicable or not?",
              "title": "Frame",
              "type": "boolean"
            },
            "chain": {
              "description": "Is 'chain' applicable or not?",
              "title": "Chain",
              "type": "boolean"
            },
            "head_lights": {
              "description": "Is 'head lights' applicable or not?",
              "title": "Head Lights",
              "type": "boolean"
            },
            "tail_lights": {
              "description": "Is 'tail lights' applicable or not?",
              "title": "Tail Lights",
              "type": "boolean"
            }
          },
          "required": [
            "feature_node_hash",
            "wheels",
            "frame",
            "chain",
            "head_lights",
            "tail_lights"
          ],
          "title": "VisibleChecklistModel",
          "type": "object"
        }
      },
      "properties": {
        "choice": {
          "description": "Choose exactly one answer from the given options.",
          "discriminator": {
            "mapping": {
              "2xlDPPAG": "#/$defs/PersonNestedModel",
              "3y6JxTUX": "#/$defs/AnimalNestedModel",
              "llw7qdWW": "#/$defs/VehicleNestedModel"
            },
            "propertyName": "feature_node_hash"
          },
          "oneOf": [
            {
              "$ref": "#/$defs/PersonNestedModel"
            },
            {
              "$ref": "#/$defs/AnimalNestedModel"
            },
            {
              "$ref": "#/$defs/VehicleNestedModel"
            }
          ],
          "title": "Choice"
        }
      },
      "required": [
        "choice"
      ],
      "title": "ObjectsRadioModel",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

**Test the Agent**

1. In your current terminal, run the following command to run the agent in debug mode.

```shell theme={"dark"}
functions-framework --target=agent --debug --source agent.py
```

2. Open your Project in the Encord platform and navigate to a frame you want to add a generic object to. Copy the URL from your browser.

<Tip>
  The url has following format: `"https://app.encord.com/label_editor/{project_hash}/{data_hash}/{frame}"`.
</Tip>

3. In another shell operating from the same working directory, source your virtual environment and test the agent.

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local agent <your_url>
```

4. To see if the test is successful, refresh your browser to view the classifications generated by Claude. Once the test runs successfully, you are ready to deploy your agent. Visit the deployment documentation to learn more.

## Video Recaptioning using GPT-4o-mini

The goals of this example are:

1. Create a Custom Agent that automatically generates multiple variations of video captions.
2. Demonstrate how to use OpenAI's GPT-4o-mini model to enhance human-created video captions with a FastAPI-based agent.

**Prerequisites**

Before you begin, ensure you have:

* Created a virtual Python environment.
* Installed all necessary dependencies.
* Have an OpenAI API key.
* Are able to [authenticate with Encord](/agents-documentation/Basics/Authentication).

Run the following commands to set up your environment:

```shell theme={"dark"}
python -m venv venv                 # Create a virtual Python environment  
source venv/bin/activate            # Activate the virtual environment  
python -m pip install encord-agents langchain-openai "fastapi[standard]" openai  # Install required dependencies  
export OPENAI_API_KEY="<your-api-key>"     # Set your OpenAI API key  
export ENCORD_SSH_KEY_FILE="/path/to/your/private/key"  # Define your Encord access key  
```

**Project Setup**

Create a Project containing videos in Encord.

This example requires an Ontology with four text classifications:

* One text classification for human-created summaries of what is happening in the video.
* Three text classifications to be automatically filled by the LLM.

**Ontology**

<img />

<AccordionGroup>
  <Accordion title="Ontology JSON and Script">
    ```json theme={"dark"}
        {
          "objects": [],
          "classifications": [
            {
              "id": "1",
              "featureNodeHash": "GCH8VHIK",
              "attributes": [
                {
                  "id": "1.1",
                  "name": "Caption",
                  "type": "text",
                  "required": false,
                  "featureNodeHash": "Yg7xXEfC"
                }
              ]
            },
            {
              "id": "2",
              "featureNodeHash": "PwQAwYid",
              "attributes": [
                {
                  "id": "2.1",
                  "name": "Caption Rephrased 1",
                  "type": "text",
                  "required": false,
                  "featureNodeHash": "aQdXJwbG"
                }
              ]
            },
            {
              "id": "3",
              "featureNodeHash": "3a/aSnHO",
              "attributes": [
                {
                  "id": "3.1",
                  "name": "Caption Rephrased 2",
                  "type": "text",
                  "required": false,
                  "featureNodeHash": "8zY6H62x"
                }
              ]
            },
            {
              "id": "4",
              "featureNodeHash": "FNjXp5TU",
              "attributes": [
                {
                  "id": "4.1",
                  "name": "Caption Rephrased 3",
                  "type": "text",
                  "required": false,
                  "featureNodeHash": "sKg1Kq/m"
                }
              ]
            }
          ]
        }
    ```

    To construct the Ontology used in this example, run the following script:

    ```python theme={"dark"}
    import json
    from encord.objects.ontology_structure import OntologyStructure
    from encord.objects.attributes import TextAttribute

    structure = OntologyStructure()
    caption = structure.add_classification()
    caption.add_attribute(TextAttribute, "Caption")
    re1 = structure.add_classification()
    re1.add_attribute(TextAttribute, "Recaption 1")
    re2 = structure.add_classification()
    re2.add_attribute(TextAttribute, "Recaption 2")
    re3 = structure.add_classification()
    re3.add_attribute(TextAttribute, "Recaption 3")

    print(json.dumps(structure.to_dict(), indent=2))

    create_ontology = False
    if create_ontology:
        from encord.user_client import EncordUserClient
        client = EncordUserClient.create_with_ssh_private_key()  # Look in auth section for authentication
        client.create_ontology("title", "description", structure)
    ```
  </Accordion>
</AccordionGroup>

The workflow for this agent is:

1. A human watches the video and enters a caption in the first text field.

2. The agent is then triggered and generates three additional caption variations for review.

* Each video is first annotated by a human (ANNOTATE stage).
* Next, a data agent automatically generates alternative captions (AGENT stage).
* Finally, a human reviews all four captions (REVIEW stage) before the task is marked complete.

<Note>
  If no human caption is present when the agent is triggered, the task is sent back for annotation.
  If the review stage results in rejection, the task is also returned for re-annotation.
</Note>

**Workflow**

<img />

**Create the Agent**

This section provides the complete code for creating your Custom Agent, along with an explanation of its internal workings.

**Agent Setup Steps**

1. Set up imports and create a Pydantic model for our LLM's structured output.
2. Create a detailed system prompt for the LLM that explains exactly what kind of rephrasing we want.
3. Configure the LLM to use structured outputs based on our model.
4. Create a helper function to prompt the model with both text and image.
5. Define the agent to handle the recaptioning. This includes:
   * Retrieving the existing human-created caption, prioritizing captions from the current frame or falling back to frame zero.
   * Sending the first frame of the video along with the human caption to the LLM.
   * Processing the response from the LLM, which provides three alternative phrasings of the original caption.
   * Updating the label row with the new captions, replacing any existing ones.

```python theme={"dark"}
# 1. Set up imports and create a Pydantic model for our LLM's structured output.
import os
from typing import Annotated

import numpy as np
from encord.exceptions import LabelRowError
from encord.objects.classification_instance import ClassificationInstance
from encord.objects.ontology_labels_impl import LabelRowV2
from langchain_openai import ChatOpenAI
from numpy.typing import NDArray
from pydantic import BaseModel

from encord_agents import FrameData
from encord_agents.gcp import Depends, editor_agent
from encord_agents.gcp.dependencies import Frame, dep_single_frame



# The response model for the agent to follow.
class AgentCaptionResponse(BaseModel):
    rephrase_1: str
    rephrase_2: str
    rephrase_3: str


# 2. Create a detailed system prompt for the LLM that explains exactly what kind of rephrasing we want.
SYSTEM_PROMPT = """
You are a helpful assistant that rephrases captions.

I will provide you with a video caption and an image of the scene of the video. 

The captions follow this format:

"The droid picks up <cup_0> and puts it on the <table_0>."

The captions that you make should replace the tags, e.g., <cup_0>, with the actual object names.
The replacements should be consistent with the scene.

Here are three rephrases: 

1. The droid picks up the blue mug and puts it on the left side of the table.
2. The droid picks up the cup and puts it to the left of the plate.
3. The droid is picking up the mug on the right side of the table and putting it down next to the plate.

You will rephrase the caption in three different ways, as above, the rephrases should be

1. Diverse in terms of adjectives, object relations, and object positions.
2. Sound in relation to the scene. You cannot talk about objects you cannot see.
3. Short and concise. Keep it within one sentence.

"""

# 3. Configure the LLM to use structured outputs based on our model.
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.4, api_key=os.environ["OPENAI_API_KEY"])
llm_structured = llm.with_structured_output(AgentCaptionResponse)


# 4. Create a helper function to prompt the model with both text and image.
def prompt_gpt(caption: str, image: Frame) -> AgentCaptionResponse:
    prompt = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {
            "role": "user",
            "content": [
                {"type": "text", "text": f"Video caption: `{caption}`"},
                image.b64_encoding(output_format="openai"),
            ],
        },
    ]
    return llm_structured.invoke(prompt)


# 5. Define the agent to handle the recaptioning. This includes:
@editor_agent()
def my_agent(
    frame_data: FrameData,
    label_row: LabelRowV2, # FrameData is automatically received by the agent
    frame_content: Annotated[NDArray[np.uint8], Depends(dep_single_frame)],
) -> None:
    # Retrieve the existing human-created caption, prioritizing captions from the current frame or falling back to frame zero.
    cap, *rs = label_row.ontology_structure.classifications

    # Read the existing human caption
    instances = label_row.get_classification_instances(
        filter_ontology_classification=cap, filter_frames=[0, frame_data.frame]
    )
    if not instances:
        # nothing to do if there are no human labels
        return
    elif len(instances) > 1:

        def order_by_current_frame_else_frame_0(
            instance: ClassificationInstance,
        ) -> bool:
            try:
                instance.get_annotation(frame_data.frame)
                return 2  # The best option
            except LabelRowError:
                pass
            try:
                instance.get_annotation(0)
                return 1
            except LabelRowError:
                return 0

        instance = sorted(instances, key=order_by_current_frame_else_frame_0)[-1]
    else:
        instance = instances[0]

    # Read the actual string caption
    caption = instance.get_answer()

    # Send the first frame of the video along with the human caption to the LLM.
    frame = Frame(frame=0, content=frame_content)
    response = prompt_gpt(caption, frame)

    # Process the response from the LLM, which provides three alternative phrasings of the original caption.
    # Update the label row with the new captions, replacing any existing ones.
    # Upsert the new captions
    for r, t in zip(rs, [response.rephrase_1, response.rephrase_2, response.rephrase_3]):
        # Overwrite any existing re-captions
        existing_instances = label_row.get_classification_instances(filter_ontology_classification=r)
        for existing_instance in existing_instances:
            label_row.remove_classification(existing_instance)

        # Create new instances
        ins = r.create_instance()
        ins.set_answer(t, attribute=r.attributes[0])
        ins.set_for_frames(0)
        label_row.add_classification_instance(ins)

    label_row.save()
```

<Tip>
  [Click here](https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/recaption_video.ipynb) for a concrete Vision Language Action model use-case.
</Tip>

**This example requires the following dependencies**:

```text theme={"dark"}
encord-agents
langchain-openai
fastapi[standard]
openai
```

**To set up and test the agent locally**:

1. Save the dependencies above into a `requirements.txt` file.

2. Set up your Python environment and run the agent:

   ```shell theme={"dark"}
   python -m venv venv
   source venv/bin/activate
   python -m pip install -r requirements.txt

   ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
   OPENAI_API_KEY=<your-api-key> \
   fastapi dev main.py
   ```

   *(Replace `/path/to/your_private_key` and `<your-api-key>` with your actual credentials.)*

3. In a separate terminal, test the agent:

   ```shell theme={"dark"}
   source venv/bin/activate
   encord-agents test local my_agent <url_from_the_label_editor>
   ```

   *(Replace `<url_from_the_label_editor>` with the URL from your Encord Label Editor session.)*

## PDF OCR Encord Agent

The goal is to create a Custom Agent that extracts text from target bounding boxes in a PDF using the Document AI API.

This Agent performs the following:

1. Searches for bounding boxes in your PDF that have a Text or OCR text attributes.

2. Rasterizes PDF pages.

3. Crops each bounding box.

4. Sends the crop to [Google Document AI OCR](https://cloud.google.com/document-ai?hl=en).

5. Writes the extracted text back into the attribute on the object.

6. Saves the label row after each batch.

**Prerequisites**

* Create a virtual Python environment
* Install all necessary dependencies
* Are able to authenticate with Encord

Run the following commands to set up your environment:

```bash theme={"dark"}
python -m venv venv       # Create a virtual Python environment
source venv/bin/activate  # Activate the virtual environment
```

**Project Setup**

<Steps>
  <Step title="Create Ontology">
    For the Agent to work, the Ontology for your Project must contain a Bounding Box object with a **Text** attribute named `Text` or `OCR`.

    For example, create an Ontology with the following:

    * PDF Document Name (bounding box)
      * Text (text attribute)

    * Error (bounding box)
      * OCR (text attribute)

    * PDF Signature Field (bounding box)
      * Signatory Name (text attribute)
      * Status (radio button)
        * Signed (radio button option)
        * Unsigned (radio button option)

    <iframe title="YouTube video player" />
  </Step>

  <Step title="Create Dataset">
    Create a Dataset that contains PDFs.

    <iframe title="YouTube video player" />
  </Step>

  <Step title="Create Project">
    Create a Project with the following:

    * Ontology you created in Step 1
    * Dataset with PDFs
    * Standard Workflow

    <iframe title="YouTube video player" />
  </Step>
</Steps>

**Host the Agent**

Use the contents of `main.py` in the process to [host the Agent](/agents-documentation/Custom-Agents/GCP-Cloud-Functions).

<CodeGroup>
  ```python main.py expandable theme={"dark"}
  import json
  import os
  from dataclasses import dataclass
  from pathlib import Path
  from typing import Annotated, Any

  import cv2
  import numpy as np
  from encord.objects.attributes import TextAttribute
  from encord.objects.common import Shape
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.ontology_labels_impl import LabelRowV2
  from encord_agents.core.data_model import FrameData
  from encord_agents.core.dependencies import Depends
  from encord_agents.gcp.dependencies import dep_asset
  from encord_agents.gcp.wrappers import editor_agent
  from google.cloud import documentai
  from pdf2image import convert_from_path

  # Set your Google Cloud Document AI API credentials path
  DOCUMENT_AI_API_DETAILS = os.environ.get("DOCUMENT_AI_API_KEY_FILE")
  if not DOCUMENT_AI_API_DETAILS:
      raise ValueError("No DOCUMENT_AI_API_KEY_FILE defined in environment variable.")

  if os.path.exists(DOCUMENT_AI_API_DETAILS):
      with open(DOCUMENT_AI_API_DETAILS, "r") as f:
          document_ai_api_details = json.load(f)

  else:
      document_ai_api_details = json.loads(DOCUMENT_AI_API_DETAILS)


  @editor_agent()
  def extract_all_bbox_text_from_pdf(
      frame_data: FrameData,
      label_row: LabelRowV2,
      asset: Annotated[Path, Depends(dep_asset)],
  ) -> None:
      bbox_text_extraction(label_row, asset, frame_data.frame, document_ai_api_details)


  def encord_bbox_to_opencv(
      bbox: BoundingBoxCoordinates, frame_width: int, frame_height: int
  ) -> tuple[int, int, int, int]:
      x = bbox.top_left_x
      y = bbox.top_left_y
      w = bbox.width
      h = bbox.height
      return (
          int(x * frame_width),
          int(y * frame_height),
          int(w * frame_width),
          int(h * frame_height),
      )


  @dataclass
  class CropData:
      """Data class to store information about a cropped region from a document."""

      feature_hash: str
      bbox: BoundingBoxCoordinates
      object: Any
      image_bytes: bytes
      frame_num: int


  def get_crops(lr: LabelRowV2, file_path: Path, frame: int) -> dict[str, CropData]:
      """Extract crops from the PDF and keep them in memory."""
      crops: dict[str, CropData] = {}
      object_instances = lr.get_object_instances()

      # Get all bounding boxes first
      for obj in object_instances:
          if obj.ontology_item.shape == Shape.BOUNDING_BOX:
              for attr in obj.ontology_item.attributes:
                  if isinstance(attr, TextAttribute):
                      crops[obj.object_hash] = CropData(
                          feature_hash=obj.feature_hash,
                          bbox=obj.get_annotations()[0].coordinates,
                          object=obj,
                          image_bytes=None,
                          frame_num=obj.get_annotations()[0].frame,
                      )

      # Convert PDF to image
      pdf_image = convert_from_path(file_path, fmt="jpeg")
      img = np.array(pdf_image)
      frame_height, frame_width = img.shape[1], img.shape[2]

      # Extract crops and convert to bytes
      for v in crops.values():
          x, y, w, h = encord_bbox_to_opencv(v.bbox, frame_width, frame_height)
          frame_img = img[v.frame_num, :, :, :]
          crop_img = frame_img[y : y + h, x : x + w]
          _, buffer = cv2.imencode(".png", crop_img)
          v.image_bytes = buffer.tobytes()

      return crops


  def process_batch_ocr(
      client: documentai.DocumentProcessorServiceClient,
      project_id: str,
      location: str,
      processor_id: str,
      batch: list[tuple[str, bytes, Any]],
  ) -> None:
      """Process a batch of images for OCR."""
      for object_hash, image_bytes, obj in batch:
          document = {
              "content": image_bytes,
              "mime_type": "image/png",
          }

          request = {
              "name": client.processor_path(project_id, location, processor_id),
              "raw_document": document,
          }

          result = client.process_document(request=request)
          ocr_text = result.document.text
          print(f"Extracted text for object {object_hash}: {ocr_text}")

          for attr in obj.ontology_item.attributes:
              if isinstance(attr, TextAttribute):
                  obj.set_answer(attribute=attr, answer=ocr_text, overwrite=True)


  def bbox_text_extraction(
      lr: LabelRowV2,
      asset: Path,
      frame_number: int,
      document_ai_api_details: dict[str, Any],
  ) -> None:
      """Extract text from bounding boxes in a PDF using OCR."""
      project_id = document_ai_api_details["project_id"]
      location = document_ai_api_details["location"]
      processor_id = document_ai_api_details["processor_id"]

      # Get crops in memory
      crops = get_crops(lr, asset, frame_number)

      # Process OCR in batches
      client = documentai.DocumentProcessorServiceClient()
      batch_size = 10  # Adjust based on your needs
      batch: list[tuple[str, bytes, Any]] = []

      for object_hash, crop_data in crops.items():
          batch.append((object_hash, crop_data.image_bytes, crop_data.object))

          if len(batch) >= batch_size:
              process_batch_ocr(client, project_id, location, processor_id, batch)
              batch = []
              lr.save()  # Save after each batch

      # Process remaining items
      if batch:
          process_batch_ocr(client, project_id, location, processor_id, batch)
          lr.save()
  ```
</CodeGroup>

**Annotate PDF**

Annotate the PDFs using the bounding boxes with `text` and `ocr` text attributes.

<iframe title="YouTube video player" />

**Run the Agent**

After Annotating the PDFs, run the Custom Agent.

<iframe title="YouTube video player" />


# Modal Examples
Source: https://docs.encord.com/agents-documentation/Custom-Agents/Examples/Modal-Examples



## Cotracker3 Keypoint Tracking

[CoTracker3](https://cotracker3.github.io/), a keypoint tracking algorithm by Meta, is an ideal example for demonstrating Modal agents. Its moderately sized (100MB) model performs excellently when deployed on Modal with serverless GPU access.

**Prerequisites**

<Tip>
  We strongly recommend first completing the general [Modal tutorial](/agents-documentation/Custom-Agents/Modal), which covers registering Encord credentials and provides simpler agent code. This example introduces a new dependency: pulling in model weights and additional ML dependencies.
</Tip>

Additionally, create a virtual environment:

```shell theme={"dark"}
python -m venv venv
source venv/bin/activate
python -m pip install encord-agents modal
```

as in the original modal tutorial.

Additionally to bring in the CoTracker dependency, we found the most straightforward way to be:

```shell theme={"dark"}
git clone https://github.com/facebookresearch/co-tracker.git
mv co-tracker/cotracker ./cotracker
```

**Create the Modal Agent**

Here is the full code for the Modal Agent.

```python theme={"dark"}
from pathlib import Path

import modal
from encord.objects.coordinates import (
    PointCoordinate,
)
from encord.objects.ontology_labels_impl import LabelRowV2
from encord.objects.ontology_object_instance import ObjectInstance
from fastapi import Depends
from typing_extensions import Annotated

from encord_agents.fastapi.dependencies import (
    FrameData,
    dep_asset,
    dep_label_row,
    dep_objects,
)

# 1. Define the Modal image.
# This specifies the base environment, installs system dependencies,
# downloads the CoTracker3 model weights, and installs Python packages.
image = (
    modal.Image.debian_slim(python_version="3.12")
    .apt_install("libgl1", "libglib2.0-0", "wget")
    .run_commands(
        "wget https://huggingface.co/facebook/cotracker3/resolve/main/scaled_offline.pth",
    )
    .pip_install(
        "fastapi[standard]",
        "encord-agents",
        "torch",
        "torchvision",
        "tqdm",
        "imageio[ffmpeg]",
    )
    .add_local_python_source("cotracker") # Assuming 'cotracker' is a local directory with CoTracker source
)

# 2. Define the Modal app.
# This creates the Modal application instance, linking it to the defined image.
app = modal.App(name="encord-agents-cotracker-3-with-model", image=image)


# Helper function to read video frames from a given path using imageio.
def read_video_from_path(path):
    import imageio
    import numpy as np

    try:
        reader = imageio.get_reader(path)
    except Exception as e:
        print("Error opening video file: ", e)
        return None
    frames = []
    for i, im in enumerate(reader):
        frames.append(np.array(im))
    return np.stack(frames)


# 3. Define the endpoint and CoTracker3 usage.
# This is the main function that runs on Modal, exposed as a web endpoint.
@app.function(
    secrets=[modal.Secret.from_name("encord-ssh-key")], # Accesses a Modal secret for Encord authentication
    gpu="L4" # Specifies that the function requires a GPU (L4 type)
)
@modal.web_endpoint(method="POST")
def cotracker3(
    frame_data: FrameData, # Injected frame metadata from Encord webhook
    lr: Annotated[LabelRowV2, Depends(dep_label_row)], # Injected label row object
    object_instances: Annotated[list[ObjectInstance], Depends(dep_objects)], # Injected list of selected objects
    asset: Annotated[Path, Depends(dep_asset)], # Injected path to the local video asset
):
    import imageio
    import numpy
    import torch
    from cotracker.predictor import CoTrackerPredictor

    # Initialize CoTracker3 model, moving to GPU if available
    model = CoTrackerPredictor(checkpoint="/scaled_offline.pth")
    if torch.cuda.is_available():
        model = model.cuda()

    # Ensure only one object is selected for tracking
    assert len(object_instances) == 1
    obj_inst = object_instances[0]
    
    # Read the video from the asset path and convert to PyTorch tensor
    video = read_video_from_path(asset)
    video_tensor = torch.from_numpy(video).permute(0, 3, 1, 2)[None].float()

    # Move video tensor to GPU if available
    if torch.cuda.is_available():
        video_tensor = video_tensor.cuda()
        
    # Extract query point from the selected object instance's annotation
    annotation = obj_inst.get_annotation(frame_data.frame)
    assert isinstance(annotation.coordinates, PointCoordinate)
    assert lr.width # Ensure label row dimensions are available
    assert lr.height

    # Prepare the query tensor for CoTracker (frame number, x-coordinate, y-coordinate)
    query = torch.tensor(
        [
            [
                frame_data.frame,
                annotation.coordinates.x * lr.width, # Convert normalized x to pixel x
                annotation.coordinates.y * lr.height, # Convert normalized y to pixel y
            ],
        ]
    )
    if torch.cuda.is_available():
        query = query.cuda()
        
    # Run CoTracker to predict tracks based on the query point
    pred_tracks, _ = model(video_tensor, queries=query[None])
    
    # Update the object instance with predicted tracks for each frame
    for frame_num, coord in enumerate(pred_tracks.reshape(-1, 2)):
        try:
            obj_inst.set_for_frames(
                coordinates=PointCoordinate(x=float(coord[0]) / lr.width, y=float(coord[1]) / lr.height),
                frames=frame_num,
            )
        except Exception:
            # Skip frames where updating might fail (e.g., if coordinates are out of bounds)
            continue
            
    # Save the updated label row with the new tracked object instance
    lr.save()
```

**Create the Modal Agent**

Once the code is saved as `app.py`, deploy it using `modal deploy app.py`.

<Note>
  This agent uses an L4 GPU, incurring usage charges, though it typically operates within Modal's \$5 free allowance.
</Note>

<Tip>
  To trigger the agent, right-click on a keypoint in the Encord platform.
</Tip>


# FastAPI
Source: https://docs.encord.com/agents-documentation/Custom-Agents/FastAPI



<Info>
  The following example shows the general structure of how to build a FastAPI application. For concrete implementations of agents with specific abilities, see the [examples section](/agents-documentation/Custom-Agents/Examples).
</Info>

## STEP 1: Create a Project

1. Create a new Encord Project:

```shell theme={"dark"}
mkdir my_project
cd my_project
```

2. Create and source a new virtual environment.

```
python -m venv venv
source venv/bin/activate
```

3. Install dependencies.

```shell theme={"dark"}
python -m pip install "fastapi[standard]" encord-agents
```

## STEP 2: Define the Agent

Create a `main.py` file using the following template:

```python title="main.py" theme={"dark"}
from typing_extensions import Annotated

from encord.objects.ontology_labels_impl import LabelRowV2
from encord_agents import FrameData
from encord_agents.fastapi import dep_label_row
from encord_agents.fastapi.cors import EncordCORSMiddleware

from fastapi import FastAPI, Depends, Form

app = FastAPI()
app.add_middleware(EncordCORSMiddleware)

@app.post("/my_agent")
def my_agent(
    frame_data: FrameData,
    label_row: Annotated[LabelRowV2, Depends(dep_label_row)],
):
    # ... Do your edits to the labels
    label_row.save()
```

Complete the `my_agent` function with the logic you want to execute when the agent is triggered.

<Tip>
  You can inject multiple different [dependencies](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#Dependencies-2) into the function if necessary.
</Tip>

You can find multiple examples of what can be done with Custom Agents [here](/agents-documentation/Custom-Agents/Examples/GCP-Examples).

## STEP 3: Test the Agent

Trigger the agent by running it locally.

```shell theme={"dark"}
ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
    fastapi dev main.py --port 8080
```

<Info>
  This means starting an API at `localhost:8080/my_agent` that expects a POST request with `JSON` data with the following format:

  ```json theme={"dark"}
  {
      "projectHash": "<project_hash>",
      "dataHash": "<data_hash>",
      "frame": <frame_number>
  }
  ```
</Info>

To test the agent endpoint, open the [Label Editor](/platform-documentation/Annotate/annotate-label-editor) in your browser on a frame where you want to run the agent. Then, copy the URL.

Open a new terminal in the `my_project` directory and run:

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local my_agent '<the_pasted_url>'
```

<Warning>
  The single quotes around `<the_pasted_url>` are important and should be there because you might copy a url with, e.g., an `&` character that have a [special meaning](https://www.howtogeek.com/439199/15-special-characters-you-need-to-know-for-bash/#amp-background-process) if it is not within a string (or escaped).
</Warning>

Refresh the Label Editor in your browser to see the effect.

## STEP 4: Deployment

<Warning>
  This section is under construction.
</Warning>

Meanwhile, refer to the [official FastAPI documentation](https://fastapi.tiangolo.com/deployment/).


# GCP Cloud Functions
Source: https://docs.encord.com/agents-documentation/Custom-Agents/GCP-Cloud-Functions



<Info>
  The following example shows the general structure of how to build a GCP cloud function.
  For concrete implementations of agents with specific abilities, see the [examples section](/agents-documentation/Custom-Agents/Examples).
</Info>

## STEP 1: Create a Project

1. Create a new Encord Project:

```shell theme={"dark"}
mkdir my_project
cd my_project
```

2. Create and source a new virtual environment.

```
python -m venv venv
source venv/bin/activate
```

3. Create a requirements file.

```requirements title="requirements.txt" theme={"dark"}
functions-framework
encord-agents
```

4. Install dependencies.

```shell theme={"dark"}
python -m pip install -r requirements.txt
```

## STEP 2: Define the Agent

Create a `main.py` file using the following template:

```python title="main.py" theme={"dark"}
from encord.objects.ontology_labels_impl import LabelRowV2

from encord_agents.core.data_model import FrameData
from encord_agents.gcp import editor_agent


@editor_agent()
def my_agent(frame_data: FrameData, label_row: LabelRowV2) -> None:
    ...
    # label_row.save()
```

Complete the `my_agent` function with the logic you want to execute when the agent is triggered.

<Tip>
  You can inject multiple different [dependencies](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#dependencies-2) into the function if necessary.
</Tip>

You can find multiple examples of what can be done with Custom Agents [here](/agents-documentation/Custom-Agents/Examples).

## STEP 3: Test the Agent

Trigger the agent by running it locally.

```shell theme={"dark"}
ENCORD_SSH_KEY_FILE=/path/to/your_private_key \
    functions-framework --target=my_agent --debug --source main.py
```

<Info>
  This means starting an API at `localhost:8080/my_agent` that expects a POST request with `JSON` data with the following format:

  ```json theme={"dark"}
  {
      "projectHash": "<project_hash>",
      "dataHash": "<data_hash>",
      "frame": <frame_number>
  }
  ```
</Info>

To test the agent endpoint, open the [Label Editor](/platform-documentation/Annotate/annotate-label-editor) in your browser on a frame where you want to run the agent. Then, copy the URL.

Open a new terminal in the `my_project` directory and run:

```shell theme={"dark"}
source venv/bin/activate
encord-agents test local my_agent '<the_pasted_url>'
```

<Warning>
  Notice the single quotes around `<the_pasted_url>`. They are important and should be there because you might copy a url with, e.g., an `&` character that have a [special meaning](https://www.howtogeek.com/439199/15-special-characters-you-need-to-know-for-bash/#amp-background-process) if it is not within a string (or escaped).
</Warning>

Refresh the Label Editor in your browser to see the effect.

## STEP 4: Deployment

To go from development to production, you must deploy your agent on the Google infrastructure.

The following example shows how you can deploy the agent to the cloud. Notice how secrets (the access key that the agent should use) are set.

```shell theme={"dark"}
gcloud functions deploy my_agent \
    --entry-point my_agent \
    --runtime python311 \
    --trigger-http \
    --allow-unauthenticated \
    --gen2 \
    --region europe-west2 \
    --set-secrets="ENCORD_SSH_KEY=SERVICE_ACCOUNT_KEY:latest"
```

See the official [Google run function deploy docs](https://cloud.google.com/functions/docs/create-deploy-gcloud) for more information.

There are a couple of things that you need to pay attention to:

* You must make sure to authenticate `gcloud` and select the appropriate project first
* You should configure a secret with the ssh\_key content. See [Google Secrets docs](https://cloud.google.com/functions/docs/configuring/secrets)


# Hosting with Modal
Source: https://docs.encord.com/agents-documentation/Custom-Agents/Modal



[Modal](https://modal.com/docs) provides a serverless cloud for engineers and researchers who want to build compute-intensive applications without thinking about infrastructure.
The cloud service is well suited for building and hosting Encord Custom Agents.

This example places a bitmask "ball" in the center of an image in the Label Editor.

<Tip>
  See the Custom Agent [examples](/agents-documentation/Custom-Agents/Examples) for more sophisticated use cases.
</Tip>

<Info>
  Everything in the *FastAPI examples* can also be done using Modal, as Modal acts as a wrapper around FastAPI.
</Info>

This page is not intended to explain everything that [Modal](https://modal.com/docs) can do -- as it does a lot --, but it does provide a working example.

<Tip>
  For a complete code example, go [here](https://github.com/encord-team/encord-agents/blob/main/examples/editor_agents/modal/editor_add_bitmask.py).
</Tip>

## STEP 1: Authentication

You need to [authenticate](/agents-documentation/Basics/Authentication) with Encord first.
Once you have a private access key (preferably corresponding to a service account), you must also ensure that you have [signed up for Modal](https://modal.com/signup).

Now you can configure the secret:

1. Go to `https://modal.com/secrets`.
2. Click "Create new secret".
3. Choose the "Custom" option.
4. Name it `encord-ssh-key` (you can choose the name but it needs to match the name in the code below).
5. Add an environment variable names `ENCORD_SSH_KEY` with the content of your private access key file. Similar to the figure below.

![Modal environment variable configuration](https://storage.googleapis.com/docs-media.encord.com/Agents/modal_setup_env_variable.png)

This setup allows `encord-agents` to authenticate with Encord using the provided key.

## STEP 2: Installation

Ensure that you have installed `encord-agents` and `modal`:

```shell theme={"dark"}
python -m venv venv
source venv/bin/activate
python -m pip install encord-agents modal
```

## STEP 3: Inspecting the Modal Template

Now you need a template for creating an endpoint that can be used for defining a Custom Agent.

The following example:

1. **Creates a Docker Image** – We define a container that includes all necessary dependencies:

   * `encord-agents`: The library for building agents
   * `modal`: For hosting the agent
   * `libgl`: Required by `opencv`

   Modal automatically handles setting up this container for you.

2. **Defines an App** – We create a FastAPI application to manage the agent's endpoints.

3. **Sets Up Authentication** – We add an endpoint that uses an access key for authentication.
   * The access key should be stored as `ENCORD_SSH_KEY`.
   * `encord-agents` automatically detects this key and use it to authenticate with the Encord SDK.

4. **Implements the Agent Logic** – defines what the agent should do when triggered.
   * Check out [these examples](/agents-documentation/Custom-Agents/Examples#fastapi-examples) to see different ways to customize your agent.

Since this is a FastAPI route, you can also take advantage of built-in dependencies from [`encord_agents.fastapi.dependencies`](/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents#dependencies-3) to simplify your setup.

```python theme={"dark"}
from typing_extensions import Annotated
from fastapi import Depends
from encord_agents.fastapi.dependencies import LabelRowV2, dep_label_row
from encord_agents import FrameData

import modal

# 1. Define the docker image to run the code.
image = (
    modal.Image.debian_slim(python_version="3.12")
    .apt_install(
        "libgl1",
        "libglib2.0-0",
    ).pip_install(
        "fastapi[standard]",
        "encord-agents",
    )
)

# 2. Define the app to  hold the endpoint
app = modal.App(name="encord-agents-add-ball", image=image)


# 3. Define the endpoint with access to the secret that we set up.
@app.function(secrets=[modal.Secret.from_name("encord-ssh-key")])
@modal.web_endpoint(method="POST")
def put_ball_on_image(
    frame_data: FrameData,
    label_row: Annotated[LabelRowV2, Depends(dep_label_row)],
):
	# 4. The agent logic goes here
	# This is really a FastAPI endpoint ✨
	...
```

Next, you must define some logic to go into the agent.

## STEP 4: Defining the Agent

The following example adds a circular bitmask in the middle of the current frame.
However, it could easily be running your own model ([even on the GPU](https://modal.com/docs/guide/gpu)).

In the function definition of your route, add the following code to:

1. Ensure that the Project's Ontology has a bitmask object. If it does not, there's nothing to do here.
2. Ensure that the task is a visual data unit (an image, image group, image sequence, or video).
3. Places a bitmask with the appropriate shape and fills in a sphere.
4. Adds the bitmask to the label row.
5. Saves the labels.

```python theme={"dark"}
@app.function(secrets=[modal.Secret.from_name("encord-ssh-key")])
@modal.web_endpoint(method="POST")
def put_ball_on_image(
    frame_data: FrameData,
    label_row: Annotated[LabelRowV2, Depends(dep_label_row)],
):
    # 1. Find the first bitmask ontology object
	#    Exit if no one is found
    bitmask_object = next(
        (o for o in label_row.ontology_structure.objects if o.shape == Shape.BITMASK),
        None,
    )
    bitmask_object = next((o for o in label_row.ontology_structure.objects if o.shape == Shape.BITMASK), None)
    if not bitmask_object:
        return

    # 2. Ensure we can read image width/height
	#	 Otherwise, it's probably not a vision asset
    w, h = label_row.width, label_row.height
    if w is None or h is None:
        return

    # 3. Construct bitmask with ball in the center
    cw, ch = w//2, h//2
    radius = min(cw, ch) // 2
    mask = np.zeros((h, w), dtype=np.uint8)
    cv2.circle(mask, (cw, ch), radius, 255, -1)  # type: ignore


    # 4. Add it as a label
    ins = bitmask_object.create_instance()
    ins.set_for_frames(
        frames=frame_data.frame,
        confidence=0.8,
        coordinates=BitmaskCoordinates(mask > 0)
    )
    label_row.add_object_instance(ins)

    # 5. Save update
    label_row.save()
```

Upon completion, the `encord_agents` library sends a 200 response to the Label Editor, causing the editor to refresh its state. The result is a sphere in the middle of the image.

## STEP 5: Testing the Agent

To test the agent, there is a dedicated CLI tool.
You must first run the agent locally (with your Python environment sourced).
Assuming that the python file you created is named `example.py`, you can run:

```shell theme={"dark"}
modal serve example.py
```

The command should print a url similar to this

```
└── 🔨 Created web function put_ball_on_image =>
    https://<your_project>-put-ball-on-image-dev.modal.run
```

Let's call it `<agent_url>`.

Now, go to the Encord Label Editor in your browser, viewing an asset for which you would like to test your agent.
Copy the url; let's call it `<editor_url>`.
It should follow this pattern:

```
https://app.encord.com/label_editor/<project_hash>/<data_hash>/<frame>
```

With the endpoint running, you can from another terminal window run:

```
encord_agents test custom '<agent_url>' '<editor_url>'
```

Where you replace the `<agent_url>` and the `<editor_url>` with the relevant urls.
You should see a green box detaining the request and the response.

If the status code is 200, refresh your browser to see the new bitmask in the Label Editor.

## STEP 6: Deployment

When you are done developing your agent, run the following to deploy your agent.

```shell theme={"dark"}
modal deploy example.py
```

Copy the displayed url and configure it in the Encord platform by following [the documentation](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview).

Once that is done, you can right-click the frame in the Label Editor to trigger the agent.


# Core
Source: https://docs.encord.com/agents-documentation/Reference/Core/Agents-Reference-Core



# Core

#### b64\_encode\_image

```python theme={"dark"}
def b64_encode_image(img: NDArray[np.uint8],
                     format: Base64Formats = ".jpg") -> str
```

Encode an image to a base64 string.

**Arguments**:

* `img` - The image to encode. Expects \[RGB] channels
* `format` - The format of the image.

**Returns**:

The base64 encoded image.

### TaskSpeedColumn Objects

```python theme={"dark"}
class TaskSpeedColumn(ProgressColumn)
```

Renders human readable transfer speed.

#### render

```python theme={"dark"}
def render(task: Task) -> Text
```

Show data transfer speed.

### LabelRowMetadataIncludeArgs Objects

```python theme={"dark"}
class LabelRowMetadataIncludeArgs(BaseModel)
```

Warning, including metadata via label rows is good for *reading* metadata
**not** for writing to the metadata.

If you need to write to metadata, use the `dep_storage_item` dependencies instead.

### LabelRowInitialiseLabelsArgs Objects

```python theme={"dark"}
class LabelRowInitialiseLabelsArgs(BaseModel)
```

Arguments used to specify how to initialize labels via the SDK.

The arguments are passed to `LabelRowV2.initialise_labels`.

### FrameData Objects

```python theme={"dark"}
class FrameData(BaseModel)
```

Holds the data sent from the Encord Label Editor at the time of triggering the agent.

#### project\_hash

The identifier of the given project.

#### data\_hash

The identifier of the given data asset.

#### frame

The frame number. If single image, it's default 0.

#### object\_hashes

Object hashes if the request was made on particular objects from the App

### Frame Objects

```python theme={"dark"}
@dataclass(frozen=True)
class Frame()
```

A dataclass to hold the content of one frame in a video.

#### frame

The frame number within the video

#### content

An \[h,w,c] np.array with color channels RGB.

#### b64\_encoding

```python theme={"dark"}
def b64_encoding(
    image_format: Literal[".jpeg", ".jpg", ".png"] = ".jpeg",
    output_format: Literal["url", "openai", "anthropic", "raw"] = "url"
) -> str | dict[str, str | dict[str, str]]
```

Get a base64 representation of the image content.

This method allows you to convert the content into a base64 representation
based on various different image encodings.
This is useful, e.g., for prompting LLMs with image content.

Please see details for formats below.

**Arguments**:

* `image_format` - Which type of image encoding to use.

* `output_format` - Different common formats.
  * `raw`: the image content as a raw b64 string
  * `url`: url encoded image content. Compatible with, e.g., `<img src="<the_encoding>" />`
  * `openai`: a dict with `type` and `image_url` keys
    \_ `anthropic`: a dict with `media_type`, `type`, and `data` keys.

* `Returns` - a dict or string depending on `output_format`.

### InstanceCrop Objects

```python theme={"dark"}
@dataclass(frozen=True)
class InstanceCrop(Frame)
```

A dataclass to hold the frame content of one object instance in a video or image.

#### instance

The [ObjectInstance](/sdk-documentation/sdk-references/objects.ontology_object_instance#objectinstance) associated to the crop.

### EditorAgentResponse Objects

```python theme={"dark"}
class EditorAgentResponse(BaseModel)
```

A base class for all return types of Custom Agent functions.

#### message

A message to be displayed to the user.

#### get\_user\_client

```python theme={"dark"}
def get_user_client(settings: Settings | None = None) -> EncordUserClient
```

Generate an user client to access Encord.

**Returns**:

An EncordUserClient authenticated with the credentials from the encord\_agents.core.settings.Settings.

#### get\_initialised\_label\_row

```python theme={"dark"}
def get_initialised_label_row(
        frame_data: FrameData,
        include_args: LabelRowMetadataIncludeArgs | None = None,
        init_args: LabelRowInitialiseLabelsArgs | None = None) -> LabelRowV2
```

Get an initialized label row from the frame\_data information.

**Arguments**:

* `frame_data` - The data pointing to the data asset.

**Raises**:

* `Exception` - If the `frame_data` cannot be matched to a label row

**Returns**:

The initialized label row.

#### download\_asset

```python theme={"dark"}
@contextmanager
def download_asset(storage_item: StorageItem,
                   frame: int | None = None) -> Generator[Path, None, None]
```

Download the asset associated to a label row to disk.

This function is a context manager. Data will be cleaned up when the context is left.

Example usage:

```python theme={"dark"}

with download_asset(storage_item, 10) as asset_path:
## In here the file exists
pixel_values = np.asarray(Image.open(asset_path))

## outside, it will be cleaned up
```

**Arguments**:

* `storage_item` - The Storage item for which you want to download the associated asset.
* `frame` - The frame that you need. If frame is none for a video, you will get the video path.

**Raises**:

* `NotImplementedError` - If you try to get all frames of an image group.
* `ValueError` - If you try to download an unsupported data type (e.g., DICOM).

**Yields**:

The file path for the requested asset.

#### get\_frame\_count

```python theme={"dark"}
def get_frame_count(storage_item: StorageItem) -> int
```

Get the number of frames in a video.

#### batch\_iterator

```python theme={"dark"}
def batch_iterator(iterator: Iterable[T],
                   batch_size: int) -> Iterable[List[T]]
```

Yield batches of items from an iterator.

**Arguments**:

* `iterator` - The source iterator
* `batch_size` - Size of each batch > 0

**Returns**:

Iterable of lists, each containing up to batch\_size items

### GenericFieldModel Objects

```python theme={"dark"}
class GenericFieldModel(BaseModel)
```

#### set\_answer

```python theme={"dark"}
def set_answer(instance: ClassificationInstance) -> None
```

This function will be called from the parsing loop to allow the model to set it self as answer
on the classification instance.

#### FieldType

Field from pydantic can be anything so hard to type. This is supposed to indicate that you should use the
`pydantic.Field` function to construct this var.

### OntologyDataModel Objects

```python theme={"dark"}
class OntologyDataModel(Generic[OntologyType])
```

Class to create a pydantic model equivalent to an arbitrary classification ontology.

The model can be used to form a json schema based on the ontology. This is useful if
you are, e.g., trying to get a structured response from an LLM.

**Example:**

```python theme={"dark"}
from pydantic import ValidationError

classifications = project.ontology_structure.classifications
objects = project.ontology_structure.classifications

data_model = OntologyDataModel([objects])
## or
data_model = OntologyDataModel([classifications])

## Get a json schema for the ontology
print(data_model.model_json_schema_str)

## Parse json following the schema into label instances
json_str = my_favourite_llm(
    f"what is this? pls follow {schema}", img
)
try:
    instances = data_model(json_str)
except ValidationError:
    # invalid json
    ...

for ins in instances:
    label_row.add_classification_instance(ins)

label_row.save()
```

**Attributes**:

ontology:
DataModel:

#### \_\_call\_\_

```python theme={"dark"}
def __call__(answer: str) -> list[ClassificationInstance] | ObjectInstance
```

Validate a json response in accordance to the pydantic model.

This function allows you to convert from a json object (e.g., coming from an llm)
back to the encord "instance format".

**Arguments**:

* `answer` - The json object as a raw string.

* `Returns` - a list of classification / object instances that you will then
  have to add to a label row.

#### validate\_json

```python theme={"dark"}
def validate_json(
        answer_str: str) -> list[ClassificationInstance] | ObjectInstance
```

Validate a json response in accordance to the pydantic model.

This function allows you to convert from a json object (e.g., coming from an llm)
back to the encord "instance format".

**Arguments**:

* `answer_str` - The json object as a raw string.

* `Returns` - a list of classification / object instances that you will then
  have to add to a label row.

Settings used throughout the module.

Note that central settings will be read via environment variables.

### Settings Objects

```python theme={"dark"}
class Settings(BaseSettings)
```

#### ssh\_key\_file

The path to the private access key file to authenticate with Encord.

Either this or the `ENCORD_SSH_KEY` needs to be set for most use-cases.
To setup a key with Encord, please see
[the platform docs](/platform-documentation/General/general-access-keys).

#### ssh\_key\_content

The content of the private access key file to authenticate with Encord.

Either this or the `ENCORD_SSH_KEY` needs to be set for most use-cases.
To setup a key with Encord, please see
[the platform docs](/platform-documentation/General/general-access-keys).

#### get\_frame

```python theme={"dark"}
def get_frame(video_path: Path, desired_frame: int) -> NDArray[np.uint8]
```

Extract an exact frame from a video.

**Arguments**:

* `video_path` - The file path to where the video is stored.
* `desired_frame` - The frame to extract

**Raises**:

* `Exception` - If the video cannot be opened properly or the requested
  frame could not be retrieved from the video.

**Returns**:

Numpy array of shape \[h, w, c] where channels are BGR.

#### write\_frame

```python theme={"dark"}
def write_frame(frame_path: Path, frame: NDArray[np.uint8]) -> None
```

Write a frame to a file.

**Arguments**:

* `frame_path` - The file path to write the frame to.
* `frame` - The frame to write.

#### iter\_video

```python theme={"dark"}
def iter_video(video_path: Path) -> Iterator[Frame]
```

Iterate video frame by frame.

**Arguments**:

* `video_path` - The file path to the video you wish to iterate.

**Raises**:

* `Exception` - If the video file could not be opened properly.

**Yields**:

Frames from the video.

#### iter\_video\_with\_indices

```python theme={"dark"}
def iter_video_with_indices(video_path: Path,
                            frame_indices: Iterable[int]) -> Iterator[Frame]
```

Iterate video frame by frame with specified frame indices.

**Arguments**:

* `video_path` - The file path to the video you wish to iterate.
* `frame_indices` - The frame indices to iterate over.

**Yields**:

Frames from the video.

This module defines dependencies available for injection within serverless Custom Agents. These dependencies can be used independently, even when reliant on other dependencies.

Note: The injection mechanism necessitates the presence of type annotations for the following parameters to ensure proper resolution.

* [`FrameData`](/agents-documentation/Reference/Core/Agents-Reference-Core#framedata-objects) is automatically injected via the api request body.
* [`Project`](/sdk-documentation/sdk-references/project) is automatically loaded based on the frame data.
* `label_row_v2` is automatically loaded based on the frame data.

```python theme={"dark"}
from encord.project import Project
from encord.objects.ontology_labels_impl import LabelRowV2
from encord_agents import FrameData
...
@editor_agent()
def my_agent(
    frame_data: FrameData,
    project: Project,
    label_row: LabelRowV2,
):
    ...
```

#### dep\_client

```python theme={"dark"}
def dep_client() -> EncordUserClient
```

Dependency to provide an authenticated user client.

**Example:**

```python theme={"dark"}
from encord.user_client import EncordUserClient
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_client
...
@editor_agent()
def (
    client: Annotated[EncordUserClient, Depends(dep_client)]
):
    # Client will authenticated and ready to use.
    client.get_dataset("")
```

#### dep\_single\_frame

```python theme={"dark"}
def dep_single_frame(storage_item: StorageItem,
                     frame_data: FrameData) -> NDArray[np.uint8]
```

Dependency to inject the first frame of the underlying asset.

The downloaded asset will be named `lr.data_hash.{suffix}`.
When the function has finished running, the downloaded file is removed from the file system.

**Example:**

```python theme={"dark"}
from encord_agents import FrameData
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_single_frame
...

@editor_agent()
def my_agent(
    frame: Annotated[NDArray[np.uint8], Depends(dep_single_frame)]
):
    assert frame.ndim == 3, "Will work"
```

**Arguments**:

* `storage_item` - The Storage item. Automatically injected (see example above).

**Returns**:

Numpy array of shape \[h, w, 3] RGB colors.

#### dep\_asset

```python theme={"dark"}
def dep_asset(storage_item: StorageItem) -> Generator[Path, None, None]
```

Returns a local file path to the data asset, temporarily stored for the duration of the agent's execution.

This dependency fetches the underlying data asset using a signed URL.

The asset is temporarily stored on disk for the duration of the task and is automatically removed once the task
completes.

**Example:**

```python theme={"dark"}
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_asset
...
runner = Runner(project_hash="<project_hash_a>")

@editor_agent()
def my_agent(
    asset: Annotated[Path, Depends(dep_asset)]
) -> None:
    asset.stat()  # read file stats
    ...
```

**Returns**:

The path to the asset.

**Raises**:

* `ValueError` - if the underlying assets are not videos, images, or audio.
* `EncordException` - if data type not supported by SDK yet.

#### dep\_video\_iterator

```python theme={"dark"}
def dep_video_iterator(
        storage_item: StorageItem) -> Generator[Iterator[Frame], None, None]
```

Dependency to inject a video frame iterator for performing operations over many frames.

**Example:**

```python theme={"dark"}
from encord_agents import FrameData
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_video_iterator
...

@editor_agent()
def my_agent(
    video_frames: Annotated[Iterator[Frame], Depends(dep_video_iterator)]
):
    for frame in video_frames:
        print(frame.frame, frame.content.shape)
```

**Arguments**:

* `storage_item` - Automatically injected storage item dependency.

**Raises**:

* `NotImplementedError` - Fails for data types other than video.

**Yields**:

An iterator.

#### dep\_data\_lookup

```python theme={"dark"}
def dep_data_lookup(
        lookup: Annotated[DataLookup,
                          Depends(DataLookup.sharable)]) -> DataLookup
```

Returns a lookup for easily retrieving data rows and storage items associated with the given task.

!!! warning "Deprecated"
`dep_data_lookup` is deprecated and will be removed in version 0.2.10.
Use `dep_storage_item` instead for accessing storage items.

**Migration Guide:**

```python theme={"dark"}
## Old way (deprecated)
from encord_agents.core.dependencies.serverless import dep_data_lookup, DataLookup

@editor_agent()
def my_agent(
    frame_data: FrameData,
    lookup: Annotated[DataLookup, Depends(dep_data_lookup)]
):
    storage_item = lookup.get_storage_item(frame_data.data_hash)
    ...

## New way (recommended)
from encord_agents.gcp.dependencies import dep_storage_item

@editor_agent()
def my_agent(
    frame_data: FrameData,
    storage_item: Annotated[StorageItem, Depends(dep_storage_item)]
):
    # storage_item is directly available
    print(storage_item.client_metadata)
    ...
```

**Arguments**:

* `lookup` - The object that you can use to lookup data rows and storage items. Automatically injected.

**Returns**:

The (shared) lookup object.

#### dep\_storage\_item

```python theme={"dark"}
def dep_storage_item(storage_item: StorageItem) -> StorageItem
```

Get the storage item associated with the underlying agent task.

The [`StorageItem`](/sdk-documentation/sdk-references/storage#storageitem-objects)
is useful for multiple things like

* Updating client metadata
* Reading file properties like storage location, fps, duration, DICOM tags, etc.

**Example**

````python theme={"dark"}

```python
from typing_extensions import Annotated
from encord.storage import StorageItem
from encord_agents.gcp import editor_agent, Depends
from encord_agents.gcp.dependencies import dep_storage_item

@editor_agent()
def my_agent(storage_item: Annotated[StorageItem, Depends(dep_storage_item)]):
    print("uuid", storage_item.uuid)
    print("client_metadata", storage_item.client_metadata)
    ...
````

#### dep\_object\_crops

```python theme={"dark"}
def dep_object_crops(
    filter_ontology_objects: list[Object | str] | None = None
) -> Callable[[FrameData, LabelRowV2, NDArray[np.uint8]], list[InstanceCrop]]
```

Returns a list of object instances and frame crops associated with each object.

One example use-case is to run each crop against a model.

**Example:**

```python theme={"dark"}
@editor_agent
def my_agent(crops: Annotated[list[InstanceCrop], Depends[dep_object_crops(filter_ontology_objects=["eBw/75bg"])]]):
    for crop in crops:
        crop.content  # <- this is raw numpy rgb values
        crop.frame    # <- this is the frame number in video
        crop.instance # <- this is the object instance from the label row
        crop.b64_encoding()  # <- a base64 encoding of the image content
    ...
```

**Arguments**:

* `filter_ontology_objects` - Specify a list of ontology objects to include.
  If provided, only instances of these object types are included.
  Strings are matched against `feature_node_hashes`.

* `Returns` - The dependency to be injected into the cloud function.

#### DEncordClient

Get an authenticated user client.

#### DObjectsInstances

Get all object instances that the agent was triggered on.
No pixels, just the annotation.

#### DObjectCrops

Get all object crops that the agent was triggered on.
The instance crop contains the object instance, the frame content (pixel values), and the frame.

#### DSingleFrame

Get the single frame that the agent was triggered on.

#### DAssetPath

Get a local file path to data asset temporarily stored till end of agent execution.

#### DVideoIterator

Get a video frame iterator for doing things over many frames.

#### DStorageItem

Get the storage item associated with the underlying agent task to, for example, read/write client metadata or read data properties.

### DataLookup Objects

```python theme={"dark"}
class DataLookup()
```

!!! warning "Deprecated"
`DataLookup` is deprecated and will be removed in version 0.2.10.

**Migration Guide:**

* For accessing storage items, use `dep_storage_item` instead:
  ```python theme={"dark"}
  # Old way (deprecated)
  from encord_agents.core.dependencies.shares import DataLookup
  lookup: Annotated[DataLookup, Depends(dep_data_lookup)]
  storage_item = lookup.get_storage_item(data_hash)

  # New way (recommended)
  from encord_agents.tasks.dependencies import dep_storage_item
  # or from encord_agents.aws.dependencies import dep_storage_item
  # or from encord_agents.gcp.dependencies import dep_storage_item
  # or from encord_agents.fastapi.dependencies import dep_storage_item
  storage_item: Annotated[StorageItem, Depends(dep_storage_item)]
  ```

#### backing\_item\_uuids

```python theme={"dark"}
@property
def backing_item_uuids() -> list[UUID]
```

Get all backing item uuids for all data rows in the data lookup.

!!! warning "Deprecated"
This property is deprecated and will be removed in version 0.2.10.
Use the EncordUserClient directly to access backing item UUIDs from label rows.

#### get\_storage\_item

```python theme={"dark"}
def get_storage_item(data_hash: str | UUID,
                     dataset_hash: str | UUID | None = None,
                     sign_url: bool = False) -> StorageItem
```

!!! warning "Deprecated"
This method is deprecated and will be removed in version 0.2.10.
Use `dep_storage_item` dependency instead.

**Arguments**:

* `data_hash` - Data hash for the asset for which you need the underlying storage item.
* `dataset_hash` - If you didn't provide the associated dataset hash in the constructor,
  this is your last chance.
* `sign_url` - If `True`, pre-fetch a signed URLs for the items (otherwise the URLs will be signed on demand).

**Raises**:

* `ValueError` - Mainly if underlying data row cannot be found.

**Returns**:

The underlying storage item from which, e.g., client metadata can be updated.

#### get\_storage\_items

```python theme={"dark"}
def get_storage_items(data_hashes: list[str | UUID],
                      dataset_hash: str | UUID | None = None,
                      sign_urls: bool = False) -> list[StorageItem]
```

!!! warning "Deprecated"
This method is deprecated and will be removed in version 0.2.10.
Use the EncordUserClient directly for bulk storage item access.

**Arguments**:

* `data_hashes` - Data hashes for the assets for which you need the underlying storage items.
* `dataset_hash` - If you didn't provided the associated dataset hash in the constructor,
  this is your last chance.
* `sign_urls` - If `True`, pre-fetch a signed URLs for the items (otherwise the URLs will be signed on demand).

**Raises**:

* `ValueError` - Mainly if underlying data row cannot be found.

**Returns**:

list of underlying storage items from which, e.g., client metadata can be updated.


# Auto Custom Agents
Source: https://docs.encord.com/agents-documentation/Reference/Custom-Agents/Agents-Reference-Custom-Agents



# AWS Lambda

## wrappers

#### editor\_agent

```python theme={"dark"}
def editor_agent(
    *,
    label_row_metadata_include_args: LabelRowMetadataIncludeArgs | None = None,
    label_row_initialise_labels_args: LabelRowInitialiseLabelsArgs
    | None = None
) -> Callable[[AgentFunction], Callable[[Dict[str, Any], Any], Dict[str,
                                                                    Any]]]
```

Wrapper to make resources available for AWS Lambda Custom Agents.

## Dependencies

### DAssetPath

Get a local file path to data asset temporarily stored till end of agent execution.

### dep\_asset

```python theme={"dark"}
def dep_asset(storage_item: StorageItem) -> Generator[Path, None, None]
```

Returns a local file path to the data asset, temporarily stored for the duration of the agent's execution.

This dependency fetches the underlying data asset using a signed URL.

The asset is temporarily stored on disk for the duration of the task and is automatically removed once the task
completes.

**Example:**

```python theme={"dark"}
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_asset
...
runner = Runner(project_hash="<project_hash_a>")

@editor_agent()
def my_agent(
    asset: Annotated[Path, Depends(dep_asset)]
) -> None:
    asset.stat()  # read file stats
    ...
```

**Returns**:

The path to the asset.

**Raises**:

* `ValueError` - if the underlying assets are not videos, images, or audio.
* `EncordException` - if data type not supported by SDK yet.

### DEncordClient

Get an authenticated user client.

### dep\_client

```python theme={"dark"}
def dep_client() -> EncordUserClient
```

Dependency to provide an authenticated user client.

**Example:**

```python theme={"dark"}
from encord.user_client import EncordUserClient
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_client
...
@editor_agent()
def (
    client: Annotated[EncordUserClient, Depends(dep_client)]
):
    # Client will authenticated and ready to use.
    client.get_dataset("")
```

### DObjectCrops

Get all object crops that the agent was triggered on.
The instance crop contains the object instance, the frame content (pixel values), and the frame.

### dep\_object\_crops

```python theme={"dark"}
def dep_object_crops(
    filter_ontology_objects: list[Object | str] | None = None
) -> Callable[[FrameData, LabelRowV2, NDArray[np.uint8]], list[InstanceCrop]]
```

Returns a list of object instances and frame crops associated with each object.

One example use-case is to run each crop against a model.

**Example:**

```python theme={"dark"}
@editor_agent
def my_agent(crops: Annotated[list[InstanceCrop], Depends[dep_object_crops(filter_ontology_objects=["eBw/75bg"])]]):
    for crop in crops:
        crop.content  # <- this is raw numpy rgb values
        crop.frame    # <- this is the frame number in video
        crop.instance # <- this is the object instance from the label row
        crop.b64_encoding()  # <- a base64 encoding of the image content
    ...
```

**Arguments**:

* `filter_ontology_objects` - Specify a list of ontology objects to include.
  If provided, only instances of these object types are included.
  Strings are matched against `feature_node_hashes`.

* `Returns` - The dependency to be injected into the cloud function.

### DObjectsInstances

Get all object instances that the agent was triggered on.
No pixels, just the annotation.

### dep\_objects

Description not available in Core reference MDX.

### DSingleFrame

Get the single frame that the agent was triggered on.

### dep\_single\_frame

```python theme={"dark"}
def dep_single_frame(storage_item: StorageItem,
                     frame_data: FrameData) -> NDArray[np.uint8]
```

Dependency to inject the first frame of the underlying asset.

The downloaded asset will be named `lr.data_hash.{suffix}`.
When the function has finished running, the downloaded file is removed from the file system.

**Example:**

```python theme={"dark"}
from encord_agents import FrameData
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_single_frame
...

@editor_agent()
def my_agent(
    frame: Annotated[NDArray[np.uint8], Depends(dep_single_frame)]
):
    assert frame.ndim == 3, "Will work"
```

**Arguments**:

* `storage_item` - The Storage item. Automatically injected (see example above).

**Returns**:

Numpy array of shape \[h, w, 3] RGB colors.

### DStorageItem

Get the storage item associated with the underlying agent task to, for example, read/write client metadata or read data properties.

## dependencies.shares

### DataLookup Objects

```python theme={"dark"}
class DataLookup()
```

!!! warning "Deprecated"
`DataLookup` is deprecated and will be removed in version 0.2.10.

**Migration Guide:**

* For accessing storage items, use `dep_storage_item` instead:
  ```python theme={"dark"}
  # Old way (deprecated)
  from encord_agents.core.dependencies.shares import DataLookup
  lookup: Annotated[DataLookup, Depends(dep_data_lookup)]
  storage_item = lookup.get_storage_item(data_hash)

  # New way (recommended)
  from encord_agents.tasks.dependencies import dep_storage_item
  # or from encord_agents.aws.dependencies import dep_storage_item
  # or from encord_agents.gcp.dependencies import dep_storage_item
  # or from encord_agents.fastapi.dependencies import dep_storage_item
  storage_item: Annotated[StorageItem, Depends(dep_storage_item)]
  ```

### dep\_storage\_item

```python theme={"dark"}
def dep_storage_item(storage_item: StorageItem) -> StorageItem
```

Get the storage item associated with the underlying agent task.

The [`StorageItem`](/sdk-documentation/sdk-references/storage#storageitem-objects)
is useful for multiple things like

* Updating client metadata
* Reading file properties like storage location, fps, duration, DICOM tags, etc.

**Example**

```python theme={"dark"}
from typing_extensions import Annotated
from encord.storage import StorageItem
from encord_agents.gcp import editor_agent, Depends
from encord_agents.gcp.dependencies import dep_storage_item

@editor_agent()
def my_agent(storage_item: Annotated[StorageItem, Depends(dep_storage_item)]):
    print("uuid", storage_item.uuid)
    print("client_metadata", storage_item.client_metadata)
    ...
```

### DVideoIterator

Get a video frame iterator for doing things over many frames.

### dep\_video\_iterator

```python theme={"dark"}
def dep_video_iterator(
        storage_item: StorageItem) -> Generator[Iterator[Frame], None, None]
```

Dependency to inject a video frame iterator for performing operations over many frames.

**Example:**

```python theme={"dark"}
from encord_agents import FrameData
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_video_iterator
...

@editor_agent()
def my_agent(
    video_frames: Annotated[Iterator[Frame], Depends(dep_video_iterator)]
):
    for frame in video_frames:
        print(frame.frame, frame.content.shape)
```

**Arguments**:

* `storage_item` - Automatically injected storage item dependency.

**Raises**:

* `NotImplementedError` - Fails for data types other than video.

**Yields**:

An iterator.

# GCP

## wrappers

#### editor\_agent

```python theme={"dark"}
def editor_agent(
    *,
    label_row_metadata_include_args: LabelRowMetadataIncludeArgs | None = None,
    label_row_initialise_labels_args: LabelRowInitialiseLabelsArgs
    | None = None,
    custom_cors_regex: str | None = None
) -> Callable[[AgentFunction], Callable[[Request], Response]]
```

Wrapper to make resources available for GCP Custom Agents.

The Custom Agents are intended to be used with dependency injections.

**Arguments**:

* `label_row_metadata_include_args` - arguments to overwrite default arguments
  on `project.list_label_rows_v2()`.
* `label_row_initialise_labels_args` - Arguments to overwrite default arguments
  on `label_row.initialise_labels(...)`
* `custom_cors_regex` - A regex to use for the CORS settings. If not provided, the default regex will be used.
  Only required if the agent is not deployed on Encord's platform.

**Returns**:

A wrapped function suitable for gcp functions.

## Dependencies

### DAssetPath

Get a local file path to data asset temporarily stored till end of agent execution.

### dep\_asset

```python theme={"dark"}
def dep_asset(storage_item: StorageItem) -> Generator[Path, None, None]
```

Returns a local file path to the data asset, temporarily stored for the duration of the agent's execution.

This dependency fetches the underlying data asset using a signed URL.

The asset is temporarily stored on disk for the duration of the task and is automatically removed once the task
completes.

**Example:**

```python theme={"dark"}
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_asset
...
runner = Runner(project_hash="<project_hash_a>")

@editor_agent()
def my_agent(
    asset: Annotated[Path, Depends(dep_asset)]
) -> None:
    asset.stat()  # read file stats
    ...
```

**Returns**:

The path to the asset.

**Raises**:

* `ValueError` - if the underlying assets are not videos, images, or audio.
* `EncordException` - if data type not supported by SDK yet.

### DEncordClient

Get an authenticated user client.

### dep\_client

```python theme={"dark"}
def dep_client() -> EncordUserClient
```

Dependency to provide an authenticated user client.

**Example:**

```python theme={"dark"}
from encord.user_client import EncordUserClient
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_client
...
@editor_agent()
def (
    client: Annotated[EncordUserClient, Depends(dep_client)]
):
    # Client will authenticated and ready to use.
    client.get_dataset("")
```

### DObjectCrops

Get all object crops that the agent was triggered on.
The instance crop contains the object instance, the frame content (pixel values), and the frame.

### dep\_object\_crops

```python theme={"dark"}
def dep_object_crops(
    filter_ontology_objects: list[Object | str] | None = None
) -> Callable[[FrameData, LabelRowV2, NDArray[np.uint8]], list[InstanceCrop]]
```

Returns a list of object instances and frame crops associated with each object.

One example use-case is to run each crop against a model.

**Example:**

```python theme={"dark"}
@editor_agent
def my_agent(crops: Annotated[list[InstanceCrop], Depends[dep_object_crops(filter_ontology_objects=["eBw/75bg"])]]):
    for crop in crops:
        crop.content  # <- this is raw numpy rgb values
        crop.frame    # <- this is the frame number in video
        crop.instance # <- this is the object instance from the label row
        crop.b64_encoding()  # <- a base64 encoding of the image content
    ...
```

**Arguments**:

* `filter_ontology_objects` - Specify a list of ontology objects to include.
  If provided, only instances of these object types are included.
  Strings are matched against `feature_node_hashes`.

* `Returns` - The dependency to be injected into the cloud function.

### DObjectsInstances

Get all object instances that the agent was triggered on.
No pixels, just the annotation.

### dep\_objects

Description not available in Core reference MDX.

### DSingleFrame

Get the single frame that the agent was triggered on.

### dep\_single\_frame

```python theme={"dark"}
def dep_single_frame(storage_item: StorageItem,
                     frame_data: FrameData) -> NDArray[np.uint8]
```

Dependency to inject the first frame of the underlying asset.

The downloaded asset will be named `lr.data_hash.{suffix}`.
When the function has finished running, the downloaded file is removed from the file system.

**Example:**

```python theme={"dark"}
from encord_agents import FrameData
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_single_frame
...

@editor_agent()
def my_agent(
    frame: Annotated[NDArray[np.uint8], Depends(dep_single_frame)]
):
    assert frame.ndim == 3, "Will work"
```

**Arguments**:

* `storage_item` - The Storage item. Automatically injected (see example above).

**Returns**:

Numpy array of shape \[h, w, 3] RGB colors.

### DStorageItem

Get the storage item associated with the underlying agent task to, for example, read/write client metadata or read data properties.

## dependencies.shares

### DataLookup Objects

```python theme={"dark"}
class DataLookup()
```

!!! warning "Deprecated"
`DataLookup` is deprecated and will be removed in version 0.2.10.

**Migration Guide:**

* For accessing storage items, use `dep_storage_item` instead:
  ```python theme={"dark"}
  # Old way (deprecated)
  from encord_agents.core.dependencies.shares import DataLookup
  lookup: Annotated[DataLookup, Depends(dep_data_lookup)]
  storage_item = lookup.get_storage_item(data_hash)

  # New way (recommended)
  from encord_agents.tasks.dependencies import dep_storage_item
  # or from encord_agents.aws.dependencies import dep_storage_item
  # or from encord_agents.gcp.dependencies import dep_storage_item
  # or from encord_agents.fastapi.dependencies import dep_storage_item
  storage_item: Annotated[StorageItem, Depends(dep_storage_item)]
  ```

### dep\_storage\_item

```python theme={"dark"}
def dep_storage_item(storage_item: StorageItem) -> StorageItem
```

Get the storage item associated with the underlying agent task.

The [`StorageItem`](/sdk-documentation/sdk-references/storage#storageitem-objects)
is useful for multiple things like

* Updating client metadata
* Reading file properties like storage location, fps, duration, DICOM tags, etc.

**Example**

```python theme={"dark"}
from typing_extensions import Annotated
from encord.storage import StorageItem
from encord_agents.gcp import editor_agent, Depends
from encord_agents.gcp.dependencies import dep_storage_item

@editor_agent()
def my_agent(storage_item: Annotated[StorageItem, Depends(dep_storage_item)]):
    print("uuid", storage_item.uuid)
    print("client_metadata", storage_item.client_metadata)
    ...
```

### DVideoIterator

Get a video frame iterator for doing things over many frames.

### dep\_video\_iterator

```python theme={"dark"}
def dep_video_iterator(
        storage_item: StorageItem) -> Generator[Iterator[Frame], None, None]
```

Dependency to inject a video frame iterator for performing operations over many frames.

**Example:**

```python theme={"dark"}
from encord_agents import FrameData
from encord_agents.gcp import editor_agent
from encord_agents.gcp.dependencies import dep_video_iterator
...

@editor_agent()
def my_agent(
    video_frames: Annotated[Iterator[Frame], Depends(dep_video_iterator)]
):
    for frame in video_frames:
        print(frame.frame, frame.content.shape)
```

**Arguments**:

* `storage_item` - Automatically injected storage item dependency.

**Raises**:

* `NotImplementedError` - Fails for data types other than video.

**Yields**:

An iterator.

# FastAPI

## cors

Convenience method to easily extend FastAPI servers
with the appropriate CORS Middleware to allow
interactions from the Encord platform.

### EncordCORSMiddleware Objects

```python theme={"dark"}
class EncordCORSMiddleware(CORSMiddleware)
```

Like a regular `fastapi.middleware.cors.CORSMiddleware` but matches against
the Encord origin by default and handles X-Encord-Editor-Agent test header

**Example:**

The CORS middleware will allow POST requests from the Encord domain.

```python theme={"dark"}
from fastapi import FastAPI
from encord_agents.fastapi.cors import EncordCORSMiddleware

app = FastAPI()
app.add_middleware(EncordCORSMiddleware)
```

### EncordTestHeaderMiddleware Objects

```python theme={"dark"}
class EncordTestHeaderMiddleware(BaseHTTPMiddleware)
```

#### dispatch

```python theme={"dark"}
async def dispatch(request: Request,
                   call_next: RequestResponseEndpoint) -> Response
```

Middleware to handle the X-Encord-Editor-Agent test header.

**Arguments**:

request (Request):
call\_next (RequestResponseEndpoint):

**Returns**:

Response

#### get\_encord\_app

```python theme={"dark"}
def get_encord_app(*, custom_cors_regex: str | None = None) -> FastAPI
```

Get a FastAPI app with the Encord middleware.

**Arguments**:

* `custom_cors_regex` *str | None, optional* - A regex to use for the CORS middleware.
  Only necessary if you are not using the default Encord domain.

**Returns**:

* `FastAPI` - A FastAPI app with the Encord middleware.

## utils

#### verify\_auth

```python theme={"dark"}
def verify_auth() -> None
```

FastAPI lifecycle start hook to fail early if access key is missing.

**Example:**

This will make the server fail early if auth is not set up.

```python theme={"dark"}
from fastapi import FastAPI

app = FastAPI(
    on_startup=[verify_auth]
```

## dependencies

Dependencies for injection in FastAPI servers.

This module contains dependencies that you can inject within your api routes.
Dependencies that depend on others don't need to be used together. They'll
work just fine alone.

Note that you can also use the function parameter:

```python theme={"dark"}
from typing_extensions import Annotated
from fastapi import Form
from encord_agents import FrameData
...
@app.post("/my-agent-route")
def my_agent(
    frame_data: FrameData,
):
    ...
```

[`FrameData`](/agents-documentation/Reference/Core/Agents-Reference-Core#framedata-objects) is automatically injected via the api request body.

#### dep\_client

```python theme={"dark"}
def dep_client() -> EncordUserClient
```

Dependency to provide an authenticated user client.

**Example**:

```python theme={"dark"}
from encord.user_client import EncordUserClient
from encord_agents.fastapi.dependencies import dep_client
...
@app.post("/my-route")
def my_route(
    client: Annotated[EncordUserClient, Depends(dep_client)]
):
    # Client will authenticated and ready to use.
```

#### dep\_label\_row\_with\_args

```python theme={"dark"}
def dep_label_row_with_args(
    label_row_metadata_include_args: LabelRowMetadataIncludeArgs | None = None,
    label_row_initialise_labels_args: LabelRowInitialiseLabelsArgs
    | None = None
) -> Callable[[FrameData], LabelRowV2]
```

Dependency to provide an initialized label row.

**Example:**

```python theme={"dark"}
from encord_agents.core.data_model import LabelRowMetadataIncludeArgs, LabelRowInitialiseLabelsArgs
from encord_agents.fastapi.dependencies import dep_label_row_with_args
...

include_args = LabelRowMetadataIncludeArgs(
    include_client_metadata=True,
    include_workflow_graph_node=True,
)
init_args = LabelRowInitialiseLabelsArgs(
    include_signed_url=True,
)

@app.post("/my-route")
def my_route(
    lr: Annotated[LabelRowV2, Depends(dep_label_row_with_args(include_args, init_args))]
):
    assert lr.is_labelling_initialised  # will work
    assert lr.client_metadata           # will be available if set already
```

**Arguments**:

* `label_row_metadata_include_args` - What arguments to include on the metadata front
* `label_row_initialise_labels_args` - How and whether to initialize the label rows

**Returns**:

The initialized label row.

#### dep\_label\_row

```python theme={"dark"}
def dep_label_row(frame_data: FrameData) -> LabelRowV2
```

Dependency to provide an initialized label row.

**Example:**

```python theme={"dark"}
from encord_agents.fastapi.dependencies import dep_label_row
...

@app.post("/my-route")
def my_route(
    lr: Annotated[LabelRowV2, Depends(dep_label_row)]
):
    assert lr.is_labelling_initialised  # will work
```

**Arguments**:

* `frame_data` - the frame data from the route. This parameter is automatically injected
  if it's a part of your route (see example above)

**Returns**:

The initialized label row.

#### dep\_storage\_item

```python theme={"dark"}
def dep_storage_item(
    label_row: Annotated[LabelRowV2, Depends(dep_label_row)],
    user_client: Annotated[EncordUserClient,
                           Depends(dep_client)]) -> StorageItem
```

Get the storage item associated with the underlying agent task.

The [`StorageItem`](/sdk-documentation/sdk-references/storage#storageitem-objects)
is useful for multiple things like

* Updating client metadata
* Reading file properties like storage location, fps, duration, DICOM tags, etc.

**Example**

```python theme={"dark"}
from encord.storage import StorageItem
from encord_agents.fastapi.dependencies import dep_storage_item

@app.post("/my-agent")
def my_agent(
    storage_item: Annotated[StorageItem, Depends(dep_storage_item)]
):
    # Client will authenticated and ready to use.
    print(storage_item.dicom_study_uid)
    print(storage_item.client_metadata)
```

#### dep\_single\_frame

```python theme={"dark"}
def dep_single_frame(storage_item: Annotated[StorageItem,
                                             Depends(dep_storage_item)],
                     frame_data: FrameData) -> NDArray[np.uint8]
```

Dependency to inject the underlying asset of the frame data.

The downloaded asset will be named `lr.data_hash.{suffix}`.
When the function has finished, the downloaded file will be removed from the file system.

**Example:**

```python theme={"dark"}
from encord_agents.fastapi.dependencies import dep_single_frame
...

@app.post("/my-route")
def my_route(
    frame: Annotated[NDArray[np.uint8], Depends(dep_single_frame)]
):
    assert arr.ndim == 3, "Will work"
```

**Arguments**:

* `storage_item` - The label row. Automatically injected (see example above).

* `frame_data` - the frame data from the route. This parameter is automatically injected
  if it's a part of your route (see example above).

* `Returns` - Numpy array of shape \[h, w, 3] RGB colors.

#### dep\_asset

```python theme={"dark"}
def dep_asset(
    storage_item: Annotated[
        StorageItem,
        Depends(dep_storage_item),
    ]
) -> Generator[Path, None, None]
```

Get a local file path to data asset temporarily stored till end of agent execution.

This dependency will fetch the underlying data asset based on a signed url.
It will temporarily store the data on disk. Once the task is completed, the
asset will be removed from disk again.

**Example:**

```python theme={"dark"}
from encord_agents.fastapi.dependencies import dep_asset
...
runner = Runner(project_hash="<project_hash_a>")

@app.post("/my-route")
def my_agent(
    asset: Annotated[Path, Depends(dep_asset)],
) -> str | None:
    asset.stat()  # read file stats
    ...
```

**Returns**:

The path to the asset.

**Raises**:

* `ValueError` - if the underlying assets are not videos, images, or audio.
* `EncordException` - if data type not supported by SDK yet.

#### dep\_video\_iterator

```python theme={"dark"}
def dep_video_iterator(
    storage_item: Annotated[StorageItem,
                            Depends(dep_storage_item)]
) -> Generator[Iterator[Frame], None, None]
```

Dependency to inject a video frame iterator for doing things over many frames.

**Example:**

```python theme={"dark"}
from encord_agents.fastapi.dependencies import dep_video_iterator, Frame
...

@app.post("/my-route")
def my_route(
    video_frames: Annotated[Iterator[Frame], Depends(dep_video_iterator)]
):
    for frame in video_frames:
        print(frame.frame, frame.content.shape)
```

**Arguments**:

* `storage_item` - Automatically injected storage item dependency.

**Raises**:

* `NotImplementedError` - Will fail for other data types than video.

**Yields**:

An iterator.

#### dep\_project

```python theme={"dark"}
def dep_project(
        frame_data: FrameData,
        client: Annotated[EncordUserClient,
                          Depends(dep_client)]) -> Project
```

Dependency to provide an instantiated
[Project](/sdk-documentation/sdk-references/project).

**Example:**

```python theme={"dark"}
from encord.project import Project
from encord_agents.fastapi.dependencies import dep_project
...
@app.post("/my-route")
def my_route(
    project: Annotated[Project, Depends(dep_project)]
):
    # Project will authenticated and ready to use.
    print(project.title)
```

**Arguments**:

frame\_data:
client:

#### dep\_data\_lookup

```python theme={"dark"}
def dep_data_lookup(
        lookup: Annotated[DataLookup, Depends(_lookup_adapter)]) -> DataLookup
```

Get a lookup to easily retrieve data rows and storage items associated with the given task.

!!! warning "Deprecated"
`dep_data_lookup` is deprecated and will be removed in version 0.2.10.
Use `dep_storage_item` instead for accessing storage items.

**Migration Guide:**

```python theme={"dark"}
## Old way (deprecated)
from encord_agents.fastapi.dependencies import dep_data_lookup, DataLookup

@app.post("/my-agent")
def my_agent(
    frame_data: FrameData,
    lookup: Annotated[DataLookup, Depends(dep_data_lookup)]
):
    storage_item = lookup.get_storage_item(frame_data.data_hash)
    print(storage_item.client_metadata)

## New way (recommended)
from encord_agents.fastapi.dependencies import dep_storage_item

@app.post("/my-agent")
def my_agent(
    frame_data: FrameData,
    storage_item: Annotated[StorageItem, Depends(dep_storage_item)]
):
    # storage_item is directly available
    print(storage_item.client_metadata)
```

**Arguments**:

* `lookup` - The object that you can use to lookup data rows and storage items. Automatically injected.

**Returns**:

The (shared) lookup object.

#### dep\_object\_crops

```python theme={"dark"}
def dep_object_crops(
    filter_ontology_objects: list[Object | str] | None = None
) -> Callable[[FrameData, LabelRowV2, NDArray[np.uint8]], list[InstanceCrop]]
```

Create a dependency that provides crops of object instances.

Useful, e.g., to be able to run each crop against a model.

**Example:**

```python theme={"dark"}
@app.post("/object_classification")
async def classify_objects(
    crops: Annotated[
        list[InstanceCrop],
        Depends(dep_object_crops(filter_ontology_objects=[generic_ont_obj])),
    ],
):
    for crop in crops:
        crop.content  # <- this is raw numpy rgb values
        crop.frame    # <- this is the frame number in video
        crop.instance # <- this is the object instance from the label row
        crop.b64_encoding()  # <- a base64 encoding of the image content
    ...
```

**Arguments**:

* `filter_ontology_objects` - Optional list of ontology objects to filter by.
  If provided, only instances of these object types will be included.
  Strings are matched against `feature_node_hashes`.

**Returns**:

A FastAPI dependency function that yields a list of InstanceCrop.


# Manual Custom Agents
Source: https://docs.encord.com/agents-documentation/Reference/Task-Agents/Agents-Reference-Task-Agents



## models

### TaskAgentReturnStruct Objects

```python theme={"dark"}
@dataclass
class TaskAgentReturnStruct()
```

Return this from your agent and we will handle propagating the updates in batches

#### pathway

The pathway that the task will follow on task completion

#### label\_row

The label to be saved (if present)

#### label\_row\_priority

The priority of the label row to be saved.

### TaskCompletionResult Objects

```python theme={"dark"}
class TaskCompletionResult(BaseModel)
```

Data model to hold information about the completion result of
`encord_agents.tasks.QueueRunner` agents.

## dependencies

#### dep\_client

```python theme={"dark"}
def dep_client() -> EncordUserClient
```

Dependency to provide an authenticated user client.

**Example:**

```python theme={"dark"}
from encord.user_client import EncordUserClient
from encord_agents.tasks.dependencies import dep_client
...
@runner.stage("<my_stage_name>")
def my_agent(
    client: Annotated[EncordUserClient, Depends(dep_client)]
) -> str:
    # Client will authenticated and ready to use.
    client.get_dataset("")
```

#### dep\_storage\_item

```python theme={"dark"}
def dep_storage_item(storage_item: StorageItem) -> StorageItem
```

Get the storage item associated with the underlying agent task.

The [`StorageItem`](/sdk-documentation/sdk-references/storage#storageitem-objects)
is useful for multiple things like

* Updating client metadata
* Reading file properties like storage location, fps, duration, DICOM tags, etc.

<Note>
  When marking an agent with the StorageItem dependency, we bulk fetch the storage items for the tasks
  and then inject them independently with each task. Trivial method for backwards compatibility. Can do: storage\_item: StorageItem directly.
</Note>

**Example**

```python theme={"dark"}
from encord.storage import StorageItem
from encord_agents.tasks.dependencies import dep_storage_item

@runner.stage(stage="<my_stage_name>")
def my_agent(storage_item: Annotated[StorageItem, Depends(dep_storage_item)]) -> str:
    print(storage_item.name)
    print(storage_item.client_metadata)
    ...
```

**Arguments**:

* `storage_item` - StorageItem

**Returns**:

The storage item.

#### dep\_single\_frame

```python theme={"dark"}
def dep_single_frame(storage_item: StorageItem) -> NDArray[np.uint8]
```

Dependency to inject the first frame of the underlying asset.

The downloaded asset will be named `lr.data_hash.{suffix}`.
When the function has finished, the downloaded file will be removed from the file system.

**Example:**

```python theme={"dark"}
from encord_agents import FrameData
from encord_agents.tasks.dependencies import dep_single_frame
...

@runner.stage("<my_stage_name>")
def my_agent(
    frame: Annotated[NDArray[np.uint8], Depends(dep_single_frame)]
) -> str:
    assert frame.ndim == 3, "Will work"
```

**Arguments**:

* `storage_item` - The Storage item. Automatically injected (see example above).

**Returns**:

Numpy array of shape \[h, w, 3] RGB colors.

#### dep\_video\_iterator

```python theme={"dark"}
def dep_video_iterator(
        storage_item: StorageItem) -> Generator[Iterator[Frame], None, None]
```

Dependency to inject a video frame iterator for doing things over many frames.
This will use OpenCV and the local backend on your machine.
Decoding support may vary dependent on the video format, codec and your local configuration

**Intended use**

```python theme={"dark"}
from encord_agents import FrameData
from encord_agents.tasks.dependencies import dep_video_iterator
...

@runner.stage("<my_stage_name>")
def my_agent(
    video_frames: Annotated[Iterator[Frame], Depends(dep_video_iterator)]
) -> str:
    for frame in video_frames:
        print(frame.frame, frame.content.shape)
```

**Arguments**:

* `storage_item` - Automatically injected Storage item dependency.

**Raises**:

* `NotImplementedError` - Will fail for other data types than video.

**Yields**:

An iterator.

#### dep\_video\_sampler

```python theme={"dark"}
def dep_video_sampler(
    storage_item: StorageItem
) -> Generator[Callable[[float | Sequence[int]], Iterable[Frame]], None, None]
```

Dependency to inject a video sampler for doing things over many frames.
This will use OpenCV and the local backend on your machine.
Decoding support may vary dependent on the video format, codec and your local configuration.

**Arguments**:

* `storage_item` - Automatically injected Storage item dependency.

  **Example:**

```python theme={"dark"}
from encord_agents.tasks.dependencies import dep_video_sampler
...
runner = Runner(project_hash="<project_hash_a>")

@runner.stage("<stage_name_or_uuid>")
def my_agent(
    video_sampler: Annotated[Callable[[float | Sequence[int]], Iterable[Frame]], Depends(dep_video_sampler)],
) -> str | None:
    for frame in video_sampler(1/5):
        # Get every 5th frame
        # i.e: [0,5,10,15,...]
    for frame in video_sampler([1, 2, 3]):
        # Get frames 1, 2, 3
    ...
```

#### dep\_asset

```python theme={"dark"}
def dep_asset(storage_item: StorageItem) -> Generator[Path, None, None]
```

Get a local file path to data asset temporarily stored till end of task execution.

This dependency will fetch the underlying data asset based on a signed url.
It will temporarily store the data on disk. Once the task is completed, the
asset will be removed from disk again.

**Example:**

```python theme={"dark"}
from encord_agents.tasks.dependencies import dep_asset
...
runner = Runner(project_hash="<project_hash_a>")

@runner.stage("<stage_name_or_uuid>")
def my_agent(
    asset: Annotated[Path, Depends(dep_asset)],
) -> str | None:
    asset.stat()  # read file stats
    ...
```

**Returns**:

The path to the asset.

**Raises**:

* `ValueError` - if the underlying assets are not videos, images, or audio.
* `EncordException` - if data type not supported by SDK yet.

### Twin Objects

```python theme={"dark"}
@dataclass(frozen=True)
class Twin()
```

Dataclass to hold "label twin" information.

#### dep\_twin\_label\_row

```python theme={"dark"}
def dep_twin_label_row(
        twin_project_hash: str,
        init_labels: bool = True,
        include_task: bool = False) -> Callable[[LabelRowV2], Twin | None]
```

Dependency to link assets between two Projects. When your `Runner` in running on
`<project_hash_a>`, you can use this to get a `Twin` of labels and the underlying
task in the "twin project" with `<project_hash_b>`.

This is useful in situations like:

* When you want to transfer labels from a source project" to a sink project.
* If you want to compare labels to labels from other projects upon label submission.
* If you want to extend an existing project with labels from another project on the same underlying data.

**Example:**

```python theme={"dark"}
from encord.workflow.common import WorkflowTask
from encord.objects.ontology_labels_impl import LabelRowV2
from encord_agents.tasks.dependencies import Twin, dep_twin_label_row
...
runner = Runner(project_hash="<project_hash_a>")

@runner.stage("<my_stage_name_in_project_a>")
def my_agent(
    project_a_label_row: LabelRowV2,
    twin: Annotated[
        Twin, Depends(dep_twin_label_row(twin_project_hash="<project_hash_b>"))
    ],
) -> str | None:
    label_row_from_project_b: LabelRowV2 = twin.label_row
    task_from_project_b: WorkflowTask = instance.get_answer(attribute=checklist_attribute)
```

**Arguments**:

* `twin_project_hash` - The project has of the twin project (attached to the same datasets)
  from which you want to load the additional data.
* `init_labels` - If true, the label row will be initialized before calling the agent.
* `include_task` - If true, the `task` field of the `Twin` will be populated. If population
  fails, e.g., for non-workflow projects, the task will also be None.

**Returns**:

The twin.

**Raises**:

* `encord.AuthorizationError` - if you do not have access to the project.

#### dep\_data\_lookup

```python theme={"dark"}
def dep_data_lookup(
        lookup: Annotated[DataLookup,
                          Depends(DataLookup.sharable)]) -> DataLookup
```

Get a lookup to easily retrieve data rows and storage items associated with the given task.

!!! warning "Deprecated"
`dep_data_lookup` is deprecated and will be removed in version 0.2.10.
Use `dep_storage_item` instead for accessing storage items.

**Migration Guide:**

```python theme={"dark"}
## Old way (deprecated)
from encord_agents.tasks.dependencies import dep_data_lookup, DataLookup

@runner.stage(stage="Agent 1")
def my_agent(
    task: AgentTask,
    lookup: Annotated[DataLookup, Depends(dep_data_lookup)]
) -> str:
    storage_item = lookup.get_storage_item(task.data_hash)
    client_metadata = storage_item.client_metadata
    ...

## New way (recommended)
from encord_agents.tasks.dependencies import dep_storage_item

@runner.stage(stage="Agent 1")
def my_agent(
    task: AgentTask,
    storage_item: Annotated[StorageItem, Depends(dep_storage_item)]
) -> str:
    # storage_item is directly available
    client_metadata = storage_item.client_metadata

    # Update metadata
    storage_item.update(
        client_metadata={
            "new": "entry",
            **(client_metadata or {})
        }
    )
    ...
```

**Arguments**:

* `lookup` - The object that you can use to lookup data rows and storage items. Automatically injected.

**Returns**:

The (shared) lookup object.

## runner.queue\_runner

### QueueRunner Objects

```python theme={"dark"}
class QueueRunner(RunnerBase)
```

This class is intended to hold agent implementations.
It makes it easy to put agent task specifications into
a queue and then execute them in a distributed fashion.

Below is a template for how that would work.

*Example:*

```python theme={"dark"}
runner = QueueRunner(project_hash="...")

@runner.stage("Agent 1")
def my_agent_implementation() -> str:
    # ... do your thing
    return "<pathway_name>"

## Populate the queue
my_queue = ...
for stage in runner.get_agent_stages():
    for task in stage.get_tasks():
        my_queue.append(task.model_dump_json())

## Execute on the queue
while my_queue:
    task_spec = my_queue.pop()
    result_json = my_agent_implementation(task_spec)
    result = TaskCompletionResult.model_validate_json(result_json)
```

#### \_\_init\_\_

```python theme={"dark"}
def __init__(project_hash: str | UUID)
```

Initialize the QueueRunner with a project hash.

This is the hash of the project that you want to run the tasks on.

**Arguments**:

* `project_hash` - The hash of the project to run the tasks on.

#### stage

```python theme={"dark"}
def stage(
    stage: str | UUID,
    *,
    label_row_metadata_include_args: LabelRowMetadataIncludeArgs | None = None,
    label_row_initialise_labels_args: LabelRowInitialiseLabelsArgs
    | None = None,
    will_set_priority: bool = False
) -> Callable[[Callable[..., TaskAgentReturnType]], Callable[[str], str]]
```

Agent wrapper intended for queueing systems and distributed workloads.

Define your agent as you are used to with dependencies in the method declaration and
return the pathway from the project workflow that the task should follow upon completion.
The function will be wrapped in logic that does the following (in pseudo code):

When you have an `encord.workflow.stages.agent.AgentTask` instance at hand, let's call
it `task`, then you can call your `wrapped_function` with `task.model_dump_json()`.
Similarly, you can put `task.model_dump_json()` int a queue and read from that queue, e.g.,
from another instance/process, to execute `wrapped_function` there.

As the pseudo code indicates, `wrapped_function` understands how to take that string from
the queue and resolve all your defined dependencies before calling `your_function`.

```
@runner.stage("stage_name")
def my_function(...)
    ...

## is equivalent to

def wrapped_function(task_json_spec: str) -> str (result_json):
    task = fetch_task(task_sped)
    resources = load_resources(task)
    pathway = your_function(resources)  # <- this is where your code goes
    task.proceed(pathway)
    return TaskCompletionResult.model_dump_json()
```

**Arguments**:

* `stage` - The name or uuid of the stage that the function should be
  associated with.
* `label_row_metadata_include_args` - Arguments to be passed to
  `project.list_label_rows_v2(...)`
* `label_row_initialise_labels_args` - Arguments to be passed to
  `label_row.initialise_labels(...)`
* `will_set_priority` - Indicates whether you will be returning a `TaskAgentReturnStruct`
  with a `label_row_priority` field set. This field is only required if you are
  returning the priority of the label row but not depending on the label row it self.
  That is, if your function signature does not include a `LabelRowV2` parameter.

**Returns**:

The decorated function.

#### get\_agent\_stages

```python theme={"dark"}
def get_agent_stages() -> Iterable[AgentStage]
```

Get the agent stages for which there exist an agent implementation.

This function is intended to make it easy to iterate through all current
agent tasks and put the task specs into external queueing systems like
Celery or Modal.

For a concrete example, please see the doc string for the class it self.

Note that if you didn't specify an implementation (by decorating your
function with `@runner.stage`) for a given agent stage, the stage will
not show up by calling this function.

**Returns**:

An iterable over `encord.workflow.stages.agent.AgentStage` objects
where the runner contains an agent implementation.

**Raises**:

* `AssertionError` - if the runner does not have an associated project.

## runner.runner\_base

### RunnerBase Objects

```python theme={"dark"}
class RunnerBase()
```

#### \_\_init\_\_

```python theme={"dark"}
def __init__(project_hash: str | UUID | None = None)
```

Initialize the runner with an optional project hash.

The `project_hash` will allow stricter stage validation.
If left unspecified, errors will first be raised during execution of the runner.

**Arguments**:

* `project_hash` - The project hash that the runner applies to.

  Can be left unspecified to be able to reuse same runner on multiple projects.

## runner.sequential\_runner

### SequentialRunner Objects

```python theme={"dark"}
class SequentialRunner(RunnerBase)
```

Runs agents against Workflow projects.

When called, it will iteratively run agent stages until they are empty. By default, runner exits after finishing the tasks identified at the point of trigger. To automatically re-run, you can use the `refresh_every` keyword.

**Example:**

```python title="example_agent.py" theme={"dark"}
from uuid import UUID
from encord_agents.tasks import Runner
runner = Runner()

@runner.stage("<workflow_node_name>")
## or
@runner.stage("<workflow_node_uuid>")
def my_agent(task: AgentTask) -> str | UUID | None:
    ...
    return "pathway name"  # or pathway uuid

runner(project_hash="<project_hash>")  # (see __call__ for more arguments)
## or
if __name__ == "__main__":
    # for CLI usage: `python example_agent.py --project-hash "<project_hash>"`
    runner.run()
```

#### \_\_init\_\_

```python theme={"dark"}
def __init__(project_hash: str | None = None,
             *,
             pre_execution_callback: Callable[[Self], None] | None = None)
```

Initialize the runner with an optional project hash.

The `project_hash` will allow stricter stage validation.
If left unspecified, errors will first be raised during execution of the runner.

**Arguments**:

* `project_hash` - The project hash that the runner applies to.

  Can be left unspecified to be able to reuse same runner on multiple projects.
* `pre_execution_callback` - Callable\[RunnerBase, None]

  Allows for optional additional validation e.g. Check specific Ontology form

#### stage

```python theme={"dark"}
def stage(
    stage: str | UUID,
    *,
    label_row_metadata_include_args: LabelRowMetadataIncludeArgs | None = None,
    label_row_initialise_labels_args: LabelRowInitialiseLabelsArgs
    | None = None,
    overwrite: bool = False,
    will_set_priority: bool = False
) -> Callable[[DecoratedCallable], DecoratedCallable]
```

Decorator to associate a function with an agent stage.

A function decorated with a stage is added to the list of stages
that will be handled by the runner.
The runner will call the function for every task which is in that
stage.

**Example:**

The function declaration can be any function that takes parameters
that are type annotated with the following types:

* \[Project]\[docs-project]: the `encord.project.Project`
  that the runner is operating on.
* \[LabelRowV2]\[docs-label-row]: the `encord.objects.LabelRowV2`
  that the task is associated with.
* \[AgentTask]\[docs-project]: the `encord.workflow.stages.agent.AgentTask`
  that the task is associated with.
* Any other type: which is annotated with a [dependency](/agents-documentation/Basics/Dependencies)

All those parameters will be automatically injected when the agent is called.

**Example:**

```python theme={"dark"}
runner = Runner()

@runner.stage("<stage_name_or_uuid>")
def my_func() -> str | None:
    ...
    return "<pathway_name or pathway_uuid>"
```

```python theme={"dark"}
from typing import Iterator
from typing_extensions import Annotated

from encord.project import Project
from encord_agents.tasks import Depends
from encord_agents.tasks.dependencies import dep_video_iterator
from encord.workflow.stages.agent import AgentTask

runner = Runner()

def random_value() -> float:
    import random
    return random.random()

@runner.stage("<stage_name_or_uuid>")
def my_func(
    project: Project,
    lr: LabelRowV2,
    task: AgentTask,
    video_frames: Annotated[Iterator[Frame], Depends(dep_video_iterator)],
    custom: Annotated[float, Depends(random_value)]
) -> str | None:
    ...
    return "<pathway_name or pathway_uuid>"
```

**Arguments**:

* `stage` - The name or uuid of the stage that the function should be
  associated with.
* `label_row_metadata_include_args` - Arguments to be passed to
  `project.list_label_rows_v2(...)`
* `label_row_initialise_labels_args` - Arguments to be passed to
  `label_row.initialise_labels(...)`
* `overwrite` - Overwrite the method associated to this stage if it already exists
  will throw an error otherwise
* `will_set_priority` - Indicates whether you will be returning a `TaskAgentReturnStruct`
  with a `label_row_priority` field set. This field is only required if you are
  returning the priority of the label row but not depending on the label row it self.
  That is, if your function signature does not include a `LabelRowV2` parameter.

**Returns**:

The decorated function.

#### \_\_call\_\_

```python theme={"dark"}
def __call__(
    refresh_every: Annotated[
        Optional[int],
        Option(
            help=
            "Fetch task statuses from the Encord Project every `refresh_every` seconds. If `None`, the runner will exit once task queue is empty."
        ),
    ] = None,
    num_retries: Annotated[
        int,
        Option(
            help=
            "If an agent fails on a task, how many times should the runner retry it?"
        )] = 3,
    task_batch_size: Annotated[
        int,
        Option(
            help=
            "Number of tasks for which labels are loaded into memory at once."
        )] = 300,
    project_hash: Annotated[
        Optional[str],
        Option(help="The project hash if not defined at runner instantiation."
               )] = None,
    max_tasks_per_stage: Annotated[
        Optional[int],
        Option(
            help=
            "Max number of tasks to try to process per stage on a given run. If `None`, will attempt all",
        ),
    ] = None
) -> None
```

Run your agent `runner(...)`.

???+ info "Self-updating/Polling runner"
The runner can continuously poll new tasks in the project and execute the defined stage agents.
To do so, please set the `refresh_every` parameter.
When set, the runner will re-fetch tasks with at least that amount of time in between polls. If you set the time to, e.g., 1 second, but it takes 60 seconds to empty the task queue, the runner will poll again upon completion of the current task queue.

**Arguments**:

* `refresh_every` - Fetch task statuses from the Encord Project every `refresh_every` seconds.
  If `None`, the runner will exit once task queue is empty.
* `num_retries` - If an agent fails on a task, how many times should the runner retry it?
* `task_batch_size` - Number of tasks for which labels are loaded into memory at once.
* `project_hash` - The project hash if not defined at runner instantiation.

**Returns**:

None

#### run

```python theme={"dark"}
def run() -> None
```

Execute the runner.

This function is intended to be called from the "main file".
It is an entry point to be able to run the agent(s) via your shell
with command line arguments.

**Example:**

You can then run execute the runner with:

to see the options is has (it's those from `Runner.__call__`).

```python title="example.py" theme={"dark"}
runner = Runner(project_hash="<your_project_hash>")

@runner.stage(stage="...")
def your_func() -> str:
    ...

if __name__ == "__main__":
    runner.run()
```

```shell theme={"dark"}
python example.py --help
```


# Custom Domain
Source: https://docs.encord.com/agents-documentation/Task-Agents/Custom-Domain



<Warning>
  The following code is for users using Encord with the US domain (`https://api.us.encord.com`) or their own private VPC (Virtual Private Cloud).
</Warning>

## STEP 1: Set the `ENCORD_DOMAIN` Environment variable

This will be the domain to the Encord API, not the front-end app.

If running locally:

```shell theme={"dark"}
export ENCORD_DOMAIN=https://api.us.encord.com
```

If running in a Python project:

```python theme={"dark"}
import os

os.environ["ENCORD_DOMAIN"] = "https://api.us.encord.com"
```

## STEP 2: Set the `ENCORD_SSH_KEY` or `ENCORD_SSH_KEY_FILE` Environment variables

If running locally:

<CodeGroup>
  ```shell Key theme={"dark"}
  export ENCORD_SSH_KEY="<your key>"
  ```

  ```shell Key Path theme={"dark"}
  export ENCORD_SSH_KEY_FILE="path/to/your/key"
  ```
</CodeGroup>

If deploying with a GCP cloud function, create a GCP secret & pass in the Key

<CodeGroup>
  ```python Key theme={"dark"}
  import os

  os.environ["ENCORD_SSH_KEY"] = "<your key>"
  ```

  ```python Key Path theme={"dark"}
  os.environ["ENCORD_SSH_KEY_FILE"] = "path/to/your/file"
  ```
</CodeGroup>

## STEP 3: Instantiate the Client from the Agent

<Warning>
  This step is only required if your agent uses the Encord Client.
</Warning>

Since Encord is a separate package than Encord-Agents, when leveraging an Encord Client, you also need to use the client connected to the agent.

For tasks that need the Encord client for every operation, we recommend:

```python theme={"dark"}
@app.post("/my-agent")
def my_agent(user_client: Annotated[EncordUserClient, Depends(dep_user_client)]):
    # use agent to get project, dataset, etc
```

If you only need the client once to do batch processing or filtering, you can fetch the existing client from the agents library:

```python theme={"dark"}
from encord_agents.core.utils import get_user_client

encord_user_client = get_user_client()
```


# Manual Agent Examples
Source: https://docs.encord.com/agents-documentation/Task-Agents/Task-Agent-Examples



<Card title="Prioritize Annotation Tasks" icon="notebook" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/task_agent_set_priority.ipynb">
  Clicking on this card brings you to the Google Colab notebook.
</Card>

## Workflow Automation & Data Management

<CardGroup>
  <Card title="Prioritize Annotation Tasks" icon="route" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/task_agent_set_priority.ipynb">
    Assign a priority to each task before advancing the task to the annotation stage.
  </Card>

  <Card title="Route Based on Previous Annotator" icon="route" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/task_agent_route_on_annotator_name.ipynb">
    Route a task according to the annotator it was annotated by.
  </Card>

  <Card title="Transferring Labels to a Twin Project" icon="route" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/twin_project_label_transfer.ipynb">
    Transfer checklist labels from Project A and convert them into radio labels in Project B.
  </Card>

  <Card title="Route Tasks Based on Object Attribute" icon="route" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/AgentRouterBasedOnAttributes.ipynb">
    Route tasks according to object attribute.
  </Card>
</CardGroup>

## Pre-Labeling

<CardGroup>
  <Card title="Pre-Label Videos using Dummy Predictions" icon="tags" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/prelabel_videos_with_bounding_boxes.ipynb">
    Pre-label videos with dummy predictions.
  </Card>

  <Card title="Pre-Label Videos with Mask R-CNN" icon="tags" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/mask_rcnn_on_videos.ipynb">
    Pre-label videos with predictions using Mask R-CNN.
  </Card>

  <Card title="Pre-Label Videos with Hugging Face" icon="tags" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/hugging_face_agent_example.ipynb">
    Pre-label videos with predictions using a Hugging Face model.
  </Card>

  <Card title="Pre-Label Videos with YOLO" icon="tags" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/yolo_example.ipynb">
    Pre-label videos with predictions using an Ultralytics YOLO model.
  </Card>
</CardGroup>

## Audio Transcription & Analysis

<AccordionGroup>
  <Accordion title="Video Tutorial - Using Audio Transcription Agents">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Audio Transcription" icon="headset" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/audio_transcription_agent_multi_speaker.ipynb">
    Transcribe and diarize audio files.
  </Card>

  <Card title="Sentiment Analysis" icon="headset" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/sentiment_analysis.ipynb">
    Analyze "high confidence" transcriptions.
  </Card>

  <Card title="Sentiment Classifications" icon="headset" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/speech_sentiment_agent_single_speaker.ipynb">
    Classify the sentiment of single-speaker audio files.
  </Card>
</CardGroup>

## LLM & VLM Agent Use Cases

<CardGroup>
  <Card title="Multimodal LLM as a Judge" icon="pen" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/llm_as_a_judge.ipynb">
    Use a Large Language Model (LLM) to evaluate and select the better product image description from two different LLM-generated descriptions.
  </Card>

  <Card title="Multistage VLM Video Captioning" icon="pen" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/multistage_video_summarisation.ipynb">
    Uses a VLM to generate frame-specific captions and compile these into a textual summary using an LLM.
  </Card>

  <Card title="Recaption video frames with an LLM" icon="pen" href="https://colab.research.google.com/github/encord-team/encord-agents/blob/main/examples/notebooks/recaption_video.ipynb">
    Use the Encord Agents Task Runner to recaption videos
  </Card>
</CardGroup>


# Annotator Training
Source: https://docs.encord.com/end-to-end/BenchmarkQA/annotator-training



Follow these steps to set up annotator training in Encord. The annotator training workflow enables you to assess the accuracy and performance of your annotation workforce.

## Overview

1. [Add your training files to Encord](/end-to-end/BenchmarkQA/annotator-training#step-1%3A-add-files-to-encord).

2. [Create a Benchmark Project](/end-to-end/BenchmarkQA/annotator-training#step-2%3A-create-a-benchmark-project)
   Establish ground truth labels by having a trusted expert annotate the data. You must complete this Project before annotator training begins.

3. [Set up Annotator Training Projects](/end-to-end/BenchmarkQA/annotator-training#step-3%3A-create-annotator-training-projects)
   You must create one training Project per annotator. Use the same Dataset as the Benchmark Project in each annotator training Project. Annotators label the data, and their work is compared against the gold standard created in the benchmark.

4. [Annotators Label Training Tasks](/end-to-end/BenchmarkQA/annotator-training#step-4%3A-annotator-training)
   Annotators must complete all the training tasks assigned to them.

5. [Evaluate Annotator Performance](/end-to-end/BenchmarkQA/annotator-training#step-5%3A-evaluate-annotators)
   Use the provided SDK script to compare annotator labels with the benchmark. Analyze the results to assess accuracy and provide targeted feedback.

## STEP 1: Add Files to Encord

You must first add your data to Encord. These files are used to train your annotators.

<Steps>
  <Step title="Create a Cloud Integration">
    Select your cloud provider:

    <div lang="en">
      <head>
        <meta />

        <meta name="viewport" />

        <title>Clickable Div</title>
      </head>

      <div>
        <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration">
          AWS Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration">
          GCP Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration">
          Azure Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-otc-integration">
          OTC Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-wasabi-integration">
          Wasabi Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-oracle-integration">
          Oracle Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-direct-access-integration">
          Direct Access Integration
        </a>
      </div>
    </div>
  </Step>

  <Step title="Create a Folder to Store your Files">
    1. Navigate to **Data** > **Files & Folders**
    2. Click the **+ New folder** button to create a new folder. Select the type of folder you want to create.

    <div>
      <img />
    </div>

    3. Give the folder a meaningful name and description.

    4. Click **Create** to create the folder.
       The folder is listed in **Files & Folders**.
  </Step>

  <Step title="Create JSON file for Registration">
    To register files from cloud storage into Encord, you must create a JSON file specifying the files you want to upload.

    <Info>
      While you can [use a CSV file](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format), we strongly recommend using JSON files for uploading cloud data to Encord for better compatibility and performance.
    </Info>

    <Tip>
      Find helpful scripts for creating JSON files for the data registration process [here](/platform-documentation/Curate/add-files/index-register-cloud-data#helpful-scripts-and-examples).
    </Tip>

    All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

    <Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data)</Note>

    <Info>Encord supports file names up to 300 characters in length for any file or video for upload.</Info>

    <Info>
      Encord enforces the following upload limits for each JSON file used for file registration:

      * Up to 1 million URLs
      * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
      * URLs can be up to 16 KB in size

      Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
    </Info>

    <Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

    <AccordionGroup>
      <Accordion title="JSON Format">
        For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

        The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

        <Note>If `skip_duplicate_urls` is set to `true`, all object URLs that exactly match existing images/videos in the dataset are skipped.</Note>

        <Accordion title="JSON for AWS">
          <AccordionGroup>
            <Accordion title="Videos">
              #### [Videos](#videos)

              **Video Metadata**

              When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

              <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "cloud-path-to-your-video-1"
                    },
                    {
                      "objectUrl": "cloud-path-to-your-video-2",
                        "videoMetadata": {
                          "fps": frames-per-second,
                          "duration": duration-in-seconds,
                          "width": frame-width,
                          "height": frame-height,
                          "file_size": file-size-in-bytes,
                          "mime_type": "MIME-file-type-extension"
                        }
                      }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/BerghouseLeopardJog.mp4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blue_bus_video.mp4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/bluemlisalphutte_flyover.mp4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake_normalized.mp4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/snow_sled.MOV"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cyclists.MP4"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Video Metadata theme={"dark"}
                {
                    "videos": [
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/video_file.mp4",
                        "videoMetadata": {
                            "fps": 23.98,
                            "duration": 29.09,
                            "width": 1280,
                            "height": 720,
                            "file_size": 5468354,
                            "mime_type": "video/mp4"
                        }
                      }
                    ],
                  "skip_duplicate_urls": true
                  }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Audio files">
              #### [Audio Files](#audio-files)

              The following is an example JSON file for uploading two audio files to Encord.

              <Tip>
                Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
              </Tip>

              * **Template:** Imports audio files with an Encord title.
              * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "audio": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-custom-audio-file-title.mp3"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Audio Metadata theme={"dark"}
                {
                    "audio": [
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file.mp3",
                        "audioMetadata": {
                            "duration": 23.98,
                            "file_size": 2900000,
                            "mime_type": "audio/mp3",
                            "sample_rate": 44100,
                            "bit_depth": 24,
                            "codec": "mp3",
                            "num_channels": 2
                        }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="PDFs">
              #### [PDFs](#pdfs)

              The following are example JSON files for uploading PDFs to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "pdfs": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-document-02.pdf"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-document-03.pdf",
                      "pdfMetadata": {
                        "fileSize": 300,
                        "numPages": 5
                        }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "pdfs": [
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-01.pdf",

                      },
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-02.pdf",
                        "title": "my-document-02.pdf"
                      },
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-03.pdf",
                        "title": "my-document-03.pdf",
                        "pdfMetadata": {
                          "fileSize": 300,
                          "numPages": 5
                          }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Text Files">
              #### [Text Files](#text-files)

              The following are example JSON files for uploading text files to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "text": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-file.html"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-plain-text-file.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "<object url_4>",
                      "title": "my-csv-file.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "<object url_5>",
                      "title": "my-xml-file.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "<object url_6>",
                      "title": "my-html-file.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "text": [
                      {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-file-01.html"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-01.txt",
                      "title": "my-plain-text-file-01.txt"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-02.txt",
                      "title": "my-plain-text-file-02.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-csv-file-01.csv",
                      "title": "my-csv-file-01.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-xml-file-01.xml",
                      "title": "my-xml-file-01.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-html-file-01.html",
                      "title": "my-html-file-01.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Single images">
              #### [Single Images](#single-images)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              The JSON structure for single images parallels that of videos.

              **Template:** Provides the proper JSON format to import images into Encord.

              **Examples:**

              * **Data** Imports the images only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "file/path/to/images/file-name-01.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-02.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-03.file-extension",
                      "title": "image-title.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data    theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.jpg"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0003.jpg"
                    },
                    {
                      "objectUrl": "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"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/large_images/pexels-ivo-rainha-00057.png"
                    }
                  ]
                }
                ```

                ```json Image Metadata theme={"dark"}

                {
                  "images": [
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/my_image.jpg",
                      "imageMetadata": {
                        "mimeType": "image/jpg",
                        "fileSize": 124,
                        "width": 640,
                        "height": 480
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image groups">
              #### [Image groups](#image-groups)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image groups are collections of images that are processed as one annotation task.
              * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
              * Image groups do NOT require 'write' permissions to your cloud storage.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the image groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "image_groups": [
                    {
                      "title": "<title 1>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                    },
                    {
                      "title": "<title 2>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image group 01",
                      "createVideo": false,
                      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg",
                      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.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 group 02",
                      "createVideo": false,
                      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0001.jpg",
                      "objectUrl_1": "<https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0002.jpg",
                      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0003.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image sequences">
              #### [Image sequences](#image-sequences)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image sequences are collections of images that are processed as one annotation task and represented as a video.
              * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
              * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
              * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

              <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the images groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "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>"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "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
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="DICOM">
              #### [DICOM](#dicom)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Each `dicom_series` element can contain one or more DICOM series.
              * Each series requires a title and at least one object URL, as shown in the example below.
              * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

              <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

              The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

              * The first series contains only a single object URL, as it is composed of a single file.
              * The second series contains 3 object URLs, as it is composed of three separate files.
              * The third series contains 2 object URLs, as it is composed of two separate files.

              <Info>
                For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
              </Info>

              ```json Template theme={"dark"}
              {
                "dicom_series": [
                  {
                    "title": "Series-1",
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series1-file.dcm"
                  },
                  {
                    "title": "Series-2",
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file1.dcm",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file2.dcm",
                    "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file3.dcm",
                  },
                    {
                    "title": "Series-3",
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file1.dcm",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file2.dcm",
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="NIfTI">
              #### [NIfTI](#nifti)

              The following is an example JSON file for uploading two NIfTI files to Encord.

              ```json Template theme={"dark"}
              {
                  "nifti": [
                    {
                      "title": "<file-1>",
                      "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                    },
                    {
                      "title": "<file-2>",
                      "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title=" Multiple file types ">
              You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

              ```json Multiple file types theme={"dark"}

              {
                "images": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/Image1.png"
                  }
                ],
                "videos": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Cooking.mp4"
                  },
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Oranges.mp4"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-samsung-light",
                    "createVideo": true,
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(32).jpg",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
                    "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
                    "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
                  },
                  {
                    "title": "apple-samsung-dark",
                    "createVideo": true,
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(32).jpg",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(33).jpg",
                    "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(34).jpg",
                    "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(35).jpg"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-ios-light",
                    "createVideo": false,
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(32).jpg",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(33).jpg"
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>
        </Accordion>

        <Accordion title="JSON for GCP">
          <AccordionGroup>
            <Accordion title="Videos">
              #### [Videos](#videos)

              **Video Metadata**

              When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

              <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "cloud-path-to-your-video-1"
                    },
                    {
                      "objectUrl": "cloud-path-to-your-video-2",
                        "videoMetadata": {
                          "fps": frames-per-second,
                          "duration": duration-in-seconds,
                          "width": frame-width,
                          "height": frame-height,
                          "file_size": file-size-in-bytes,
                          "mime_type": "MIME-file-type-extension"
                        }
                      }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/eLeopardJog.mp4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/_video.mp4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/bluemlisalphutte_flyover.mp4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake_normalized.mp4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/snow_sled.MOV"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/cyclists.MP4"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Video Metadata theme={"dark"}
                {
                    "videos": [
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/video_file.mp4",
                        "videoMetadata": {
                            "fps": 23.98,
                            "duration": 29.09,
                            "width": 1280,
                            "height": 720,
                            "file_size": 5468354,
                            "mime_type": "video/mp4"
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                  }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Audio files">
              #### [Audio Files](#audio-files)

              The following is an example JSON file for uploading two audio files to Encord.

              <Tip>
                Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
              </Tip>

              * Example 1 imports audio files with an Encord title.
              * Example 2 imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "audio": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-custom-audio-file-title.mp3"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Audio Metadata theme={"dark"}
                {
                    "audio": [
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/audio_file.mp3",
                        "audioMetadata": {
                            "duration": 23.98,
                            "file_size": 2900000,
                            "mime_type": "audio/mp3",
                            "sample_rate": 44100,
                            "bit_depth": 24,
                            "codec": "mp3",
                            "num_channels": 2
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="PDFs">
              #### [PDFs](#pdfs)

              The following are example JSON files for uploading PDFs to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "pdfs": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-document-02.pdf"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-document-03.pdf",
                      "pdfMetadata": {
                        "fileSize": 300,
                        "numPages": 5
                        }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "pdfs": [
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-01.pdf",

                      },
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-02.pdf",
                        "title": "my-document-02.pdf"
                      },
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-03.pdf",
                        "title": "my-document-03.pdf",
                        "pdfMetadata": {
                          "fileSize": 300,
                          "numPages": 5
                          }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Text Files">
              #### [Text Files](#text-files)

              The following are example JSON files for uploading text files to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "text": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-file.html"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-plain-text-file.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "<object url_4>",
                      "title": "my-csv-file.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "<object url_5>",
                      "title": "my-xml-file.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "<object url_6>",
                      "title": "my-html-file.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "text": [
                      {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-file-01.html"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-01.txt",
                      "title": "my-plain-text-file-01.txt"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-02.txt",
                      "title": "my-plain-text-file-02.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-csv-file-01.csv",
                      "title": "my-csv-file-01.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-xml-file-01.xml",
                      "title": "my-xml-file-01.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-html-file-01.html",
                      "title": "my-html-file-01.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Single images">
              #### [Single Images](#single-images)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              The JSON structure for single images parallels that of videos.

              **Template:** Provides the proper JSON format to import images into Encord.

              **Examples:**

              * **Data** Imports the images only.

              * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "file/path/to/images/file-name-01.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-02.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-03.file-extension",
                      "title": "image-title.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/0001.jpg"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0003.jpg"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/large_images/pexels-ivo-rainha-00057.png"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Image Metadata theme={"dark"}

                {
                  "images": [
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/my_image.jpg",
                      "imageMetadata": {
                        "mimeType": "image/jpg",
                        "fileSize": 124,
                        "width": 640,
                        "height": 480
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image groups">
              #### [Image groups](#image-groups)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image groups are collections of images that are processed as one annotation task.
              * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
              * Image groups do NOT require 'write' permissions to your cloud storage.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the image groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "image_groups": [
                    {
                      "title": "<title 1>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                    },
                    {
                      "title": "<title 2>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image group 01",
                      "createVideo": false,
                      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/0001.jpg",
                      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg",
                      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "title": "Image group 02",
                      "createVideo": false,
                      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0001.jpg",
                      "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-0002.jpg",
                      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0003.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image sequences">
              #### [Image sequences](#image-sequences)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image sequences are collections of images that are processed as one annotation task and represented as a video.
              * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
              * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
              * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

              <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the images groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "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>"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image sequence 001",
                      "createVideo": true,
                      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/01.jpg",
                      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/02.jpg",
                      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/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://storage.cloud.google.com/encord-image-bucket/images/thing-01.jpg",
                      "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-02.jpg",
                      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-03.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="DICOM">
              #### [DICOM](#dicom)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Each `dicom_series` element can contain one or more DICOM series.
              * Each series requires a title and at least one object URL, as shown in the example below.
              * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

              <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

              The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

              * The first series contains only a single object URL, as it is composed of a single file.
              * The second series contains 3 object URLs, as it is composed of three separate files.
              * The third series contains 2 object URLs, as it is composed of two separate files.

              <Info>
                For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
              </Info>

              ```json JSON for DICOM theme={"dark"}
              {
                "dicom_series": [
                  {
                    "title": "Series-1",
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series1-file.dcm"
                  },
                  {
                    "title": "Series-2",
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file1.dcm",
                    "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file2.dcm",
                    "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file3.dcm",
                  },
                    {
                    "title": "Series-3",
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file1.dcm",
                    "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file2.dcm",
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="NIfTI">
              #### [NIfTI](#nifti)

              The following is an example JSON file for uploading two NIfTI files to Encord.

              ```json theme={"dark"}
              {
                  "nifti": [
                    {
                      "title": "<file-1>",
                      "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                    },
                    {
                      "title": "<file-2>",
                      "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title=" Multiple file types ">
              You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

              ```json Multiple file types theme={"dark"}

              {
                "images": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/Image1.png"
                  }
                ],
                "videos": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Cooking.mp4"
                  },
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Oranges.mp4"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-samsung-light",
                    "createVideo": true,
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/1+(32).jpg",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
                    "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
                    "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
                  },
                  {
                    "title": "apple-samsung-dark",
                    "createVideo": true,
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/2+(32).jpg",
                    "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/2+(33).jpg",
                    "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/2+(34).jpg",
                    "objectUrl_3": "https://storage.cloud.google.com/encord-image-bucket/images/2+(35).jpg"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-ios-light",
                    "createVideo": false,
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/3+(32).jpg",
                    "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/3+(33).jpg"
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>
        </Accordion>

        <Accordion title="JSON for Azure">
          <AccordionGroup>
            <Accordion title="Videos">
              #### [Videos](#videos)

              **Video Metadata**

              When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

              <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "cloud-path-to-your-video-1"
                    },
                    {
                      "objectUrl": "cloud-path-to-your-video-2",
                        "videoMetadata": {
                          "fps": frames-per-second,
                          "duration": duration-in-seconds,
                          "width": frame-width,
                          "height": frame-height,
                          "file_size": file-size-in-bytes,
                          "mime_type": "MIME-file-type-extension"
                        }
                      }
                    {
                      "objectUrl": "cloud-path-to-your-video-3",
                      "title": "title-for-your-video-3"

                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/BerghouseLeopardJog.mp4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/blue_bus_video.mp4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/bluemlisalphutte_flyover.mp4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake_normalized.mp4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/snow_sled.MOV"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/cyclists.MP4"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Video Metadata theme={"dark"}
                {
                    "videos": [
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/video_file.mp4",
                        "videoMetadata": {
                            "fps": 23.98,
                            "duration": 29.09,
                            "width": 1280,
                            "height": 720,
                            "file_size": 5468354,
                            "mime_type": "video/mp4"
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                  }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Audio files">
              #### [Audio Files](#audio-files)

              The following is an example JSON file for uploading two audio files to Encord.

              <Tip>
                Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
              </Tip>

              * **Template:** Imports audio files with an Encord title.
              * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "audio": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-custom-audio-file-title.mp3"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Audio Metadata theme={"dark"}
                {
                    "audio": [
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/audio_file.mp3",
                        "audioMetadata": {
                            "duration": 23.98,
                            "file_size": 2900000,
                            "mime_type": "audio/mp3",
                            "sample_rate": 44100,
                            "bit_depth": 24,
                            "codec": "mp3",
                            "num_channels": 2
                        }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="PDFs">
              #### [PDFs](#pdfs)

              The following are example JSON files for uploading PDFs to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "pdfs": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-document-02.pdf"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-document-03.pdf",
                      "pdfMetadata": {
                        "fileSize": 300,
                        "numPages": 5
                        }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "pdfs": [
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-01.pdf",

                      },
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-02.pdf",
                        "title": "my-document-02.pdf"
                      },
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-03.pdf",
                        "title": "my-document-03.pdf",
                        "pdfMetadata": {
                          "fileSize": 300,
                          "numPages": 5
                          }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Text Files">
              #### [Text Files](#text-files)

              The following are example JSON files for uploading text files to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "text": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-file.html"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-plain-text-file.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "<object url_4>",
                      "title": "my-csv-file.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "<object url_5>",
                      "title": "my-xml-file.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "<object url_6>",
                      "title": "my-html-file.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "text": [
                      {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-file-01.html"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-01.txt",
                      "title": "my-plain-text-file-01.txt"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-02.txt",
                      "title": "my-plain-text-file-02.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-csv-file-01.csv",
                      "title": "my-csv-file-01.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-xml-file-01.xml",
                      "title": "my-xml-file-01.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-html-file-01.html",
                      "title": "my-html-file-01.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Single images">
              #### [Single Images](#single-images)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              The JSON structure for single images parallels that of videos.

              **Template:** Provides the proper JSON format to import images into Encord.

              **Examples:**

              * **Data** Imports the images only.

              * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "file/path/to/images/file-name-01.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-02.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-03.file-extension",
                      "title": "image-title.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0003.jpg"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/large_images/pexels-ivo-rainha-00057.png"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Image Metadata theme={"dark"}

                {
                  "images": [
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my_image.jpg",
                      "imageMetadata": {
                        "mimeType": "image/jpg",
                        "fileSize": 124,
                        "width": 640,
                        "height": 480
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image groups">
              #### [Image groups](#image-groups)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image groups are collections of images that are processed as one annotation task.
              * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
              * Image groups do NOT require 'write' permissions to your cloud storage.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the image groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "image_groups": [
                    {
                      "title": "<title 1>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                    },
                    {
                      "title": "<title 2>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image group 01",
                      "createVideo": false,
                      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg",
                      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg",
                      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "title": "Image group 02",
                      "createVideo": false,
                      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0001.jpg",
                      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0002.jpg",
                      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-0003.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image sequences">
              #### [Image sequences](#image-sequences)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image sequences are collections of images that are processed as one annotation task and represented as a video.
              * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
              * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
              * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

              <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the images groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "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>"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image sequence 001",
                      "createVideo": true,
                      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/01.jpg",
                      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/02.jpg",
                      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/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://myaccount.blob.core.windows.net/encordcontainer/thing-01.jpg",
                      "objectUrl_1": "<https://myaccount.blob.core.windows.net/encordcontainer/thing-02.jpg",
                      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-03.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="DICOM">
              #### [DICOM](#dicom)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Each `dicom_series` element can contain one or more DICOM series.
              * Each series requires a title and at least one object URL, as shown in the example below.
              * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

              <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

              The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

              * The first series contains only a single object URL, as it is composed of a single file.
              * The second series contains 3 object URLs, as it is composed of three separate files.
              * The third series contains 2 object URLs, as it is composed of two separate files.

              <Info>
                For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
              </Info>

              ```json Template theme={"dark"}
              {
                "dicom_series": [
                  {
                    "title": "Series-1",
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series1-file.dcm"
                  },
                  {
                    "title": "Series-2",
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file1.dcm",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file2.dcm",
                    "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file3.dcm",
                  },
                    {
                    "title": "Series-3",
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file1.dcm",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file2.dcm",
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="NIfTI">
              #### [NIfTI](#nifti)

              The following is an example JSON file for uploading two NIfTI files to Encord.

              ```json Template theme={"dark"}
              {
                  "nifti": [
                    {
                      "title": "<file-1>",
                      "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                    },
                    {
                      "title": "<file-2>",
                      "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title=" Multiple file types ">
              You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

              ```json theme={"dark"}

              {
                "images": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Image1.png"
                  }
                ],
                "videos": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Cooking.mp4"
                  },
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Oranges.mp4"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-samsung-light",
                    "createVideo": true,
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(32).jpg",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(33).jpg",
                    "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(34).jpg",
                    "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(35).jpg"
                  },
                  {
                    "title": "apple-samsung-dark",
                    "createVideo": true,
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(32).jpg",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(33).jpg",
                    "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(34).jpg",
                    "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(35).jpg"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-ios-light",
                    "createVideo": false,
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(32).jpg",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(33).jpg"
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>
        </Accordion>

        <Accordion title="JSON for OTC">
          <AccordionGroup>
            <Accordion title="Videos">
              #### [Videos](#videos)

              **Video Metadata**

              When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

              <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "cloud-path-to-your-video-1"
                    },
                    {
                      "objectUrl": "cloud-path-to-your-video-2",
                        "videoMetadata": {
                          "fps": frames-per-second,
                          "duration": duration-in-seconds,
                          "width": frame-width,
                          "height": frame-height,
                          "file_size": file-size-in-bytes,
                          "mime_type": "MIME-file-type-extension"
                        }
                      }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/og.mp4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/blue_bus_video.mp4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/bluemlisalphutte_flyover.mp4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake_normalized.mp4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/snow_sled.MOV"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/cyclists.MP4"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Video Metadata theme={"dark"}
                {
                    "videos": [
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/video_file.mp4",
                        "videoMetadata": {
                            "fps": 23.98,
                            "duration": 29.09,
                            "width": 1280,
                            "height": 720,
                            "file_size": 5468354,
                            "mime_type": "video/mp4"
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                  }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Audio files">
              #### [Audio Files](#audio-files)

              The following is an example JSON file for uploading two audio files to Encord.

              <Tip>
                Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
              </Tip>

              * **Template:**  Imports audio files with an Encord title.
              * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "audio": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-custom-audio-file-title.mp3"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Audio Metadata theme={"dark"}
                {
                    "audio": [
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/audio/audio_file.mp3",
                        "audioMetadata": {
                            "duration": 23.98,
                            "file_size": 2900000,
                            "mime_type": "audio/mp3",
                            "sample_rate": 44100,
                            "bit_depth": 24,
                            "codec": "mp3",
                            "num_channels": 2
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="PDFs">
              #### [PDFs](#pdfs)

              The following are example JSON files for uploading PDFs to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "pdfs": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-document-02.pdf"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-document-03.pdf",
                      "pdfMetadata": {
                        "fileSize": 300,
                        "numPages": 5
                        }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "pdfs": [
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-01.pdf",

                      },
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-02.pdf",
                        "title": "my-document-02.pdf"
                      },
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-3.pdf",
                        "title": "my-document-03.pdf",
                        "pdfMetadata": {
                          "fileSize": 300,
                          "numPages": 5
                          }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Text Files">
              #### [Text Files](#text-files)

              The following are example JSON files for uploading text files to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "text": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-file.html"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-plain-text-file.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "<object url_4>",
                      "title": "my-csv-file.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "<object url_5>",
                      "title": "my-xml-file.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "<object url_6>",
                      "title": "my-html-file.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "text": [
                      {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-file-01.html"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-01.txt",
                      "title": "my-plain-text-file-01.txt"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-02.txt",
                      "title": "my-plain-text-file-02.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-csv-file-01.csv",
                      "title": "my-csv-file-01.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-xml-file-01.xml",
                      "title": "my-xml-file-01.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-html-file-01.html",
                      "title": "my-html-file-01.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Single images">
              #### [Single Images](#single-images)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              The JSON structure for single images parallels that of videos.

              **Template:** Provides the proper JSON format to import images into Encord.

              **Examples:**

              * **Data** Imports the images only.

              * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "file/path/to/images/file-name-01.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-02.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-03.file-extension",
                      "title": "image-title.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0003.jpg"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/large_images/pexels-ivo-rainha-00057.png"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Image Metadata theme={"dark"}

                {
                  "images": [
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my_image.jpg",
                      "imageMetadata": {
                        "mimeType": "image/jpg",
                        "fileSize": 124,
                        "width": 640,
                        "height": 480
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image groups">
              #### [Image groups](#image-groups)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image groups are collections of images that are processed as one annotation task.
              * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
              * Image groups do NOT require 'write' permissions to your cloud storage.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the image groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "image_groups": [
                    {
                      "title": "<title 1>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                    },
                    {
                      "title": "<title 2>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                      "clientMetadata": {"optional": "metadata"}
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image group 01",
                      "createVideo": false,
                      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg",
                      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg",
                      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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 group 02",
                      "createVideo": false,
                      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0001.jpg",
                      "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0002.jpg",
                      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0003.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image sequences">
              #### [Image sequences](#image-sequences)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image sequences are collections of images that are processed as one annotation task and represented as a video.
              * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
              * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
              * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

              <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the images groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "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>"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image sequence 001",
                      "createVideo": true,
                      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/01.jpg",
                      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/02.jpg",
                      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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-bucket.obs.eu-de.otc.t-systems.com/images/thing-01.jpg",
                      "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-02.jpg",
                      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-03.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="DICOM">
              #### [DICOM](#dicom)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Each `dicom_series` element can contain one or more DICOM series.
              * Each series requires a title and at least one object URL, as shown in the example below.
              * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

              <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

              The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

              * The first series contains only a single object URL, as it is composed of a single file.
              * The second series contains 3 object URLs, as it is composed of three separate files.
              * The third series contains 2 object URLs, as it is composed of two separate files.

              <Info>
                For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
              </Info>

              ```json JSON for DICOM theme={"dark"}
              {
                "dicom_series": [
                  {
                    "title": "Series-1",
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series1-file.dcm"
                  },
                  {
                    "title": "Series-2",
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file1.dcm",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file2.dcm",
                    "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file3.dcm",
                  },
                    {
                    "title": "Series-3",
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file1.dcm",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file2.dcm",
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="NIfTI">
              #### [NIfTI](#nifti)

              The following is an example JSON file for uploading two NIfTI files to Encord.

              ```json theme={"dark"}
              {
                  "nifti": [
                    {
                      "title": "<file-1>",
                      "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                    },
                    {
                      "title": "<file-2>",
                      "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title=" Multiple file types ">
              You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

              ```json Multiple file types theme={"dark"}

              {
                "images": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/Image1.png"
                  }
                ],
                "videos": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Cooking.mp4"
                  },
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Oranges.mp4"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-samsung-light",
                    "createVideo": true,
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(32).jpg",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(33).jpg",
                    "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(34).jpg",
                    "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(35).jpg"
                  },
                  {
                    "title": "apple-samsung-dark",
                    "createVideo": true,
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(32).jpg",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(33).jpg",
                    "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(34).jpg",
                    "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(35).jpg"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-ios-light",
                    "createVideo": false,
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(32).jpg",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(33).jpg"
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>
        </Accordion>

        <Accordion title="JSON for AWS Multi-Region Access Point">
          When using a Multi-Region Access Point for your AWS S3 buckets the JSON file has to be slightly different from the examples provided. Instead of an object's URL, objects are specified using the ARN of the Multi-Region Access Point followed by the object name. The example below shows how video files from a Multi-Region Access Point would be specified.

          ```json theme={"dark"}
          {
            "videos": [
              {
                "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
              },
              {
                "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
                "title": "my-custom-video-title.mp4"
              }
            ],
            "skip_duplicate_urls": true
          }
          ```

          ```json MRAP Example theme={"dark"}
          {
            "videos": [
              {
                "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_1.mp4"
              },
              {
                "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_2.mp4",
                "title": "many-cute-cats.mp4"
              }
            ],
            "skip_duplicate_urls": true
          }
          ```
        </Accordion>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Import your Files">
    <AccordionGroup>
      <Accordion title="Import cloud data">
        <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

        1. Navigate to **Data** > **Files & Folders** in the Encord platform.
        2. Click into a Folder.
        3. Click **+ Upload files**.
           A dialog appears.

        <div>
          <img />
        </div>

        4. Click **Import from cloud data**.

        <div>
          <img />
        </div>

        <Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

        6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Import local data">
        <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

        1. Navigate to **Data** > **Files & Folders** in the Encord platform.
        2. Click into a Folder.
        3. Click **+ Upload files**.
           A dialog appears.

        <img />

        4. Click one of the following:
           * **Upload:** Upload images, videos, and audio files.
             ![Upload dialog](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-001.png)
           * **Batch images as:** Upload image batches as image groups or image sequences.
             ![Batch images as](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-02.png)
           * **DICOM/NifTi:** Upload DICOM or NifTi series.
             ![DICOM/NifTi](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-03.png)

        5. Click **Upload** after selecting your images or series.

           Your files upload into the Folder in Encord.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## STEP 2: Create a Benchmark Project

<Info>
  The benchmark Project contains reference labels used to evaluate your annotators' labels. These gold standard labels should be created by a trusted expert to ensure accurate assessment.
</Info>

<Steps>
  <Step title="Create a Training Dataset">
    Create a Dataset containing tasks designed to establish ground truth labels. These files are used to generate 'gold-standard' labels against which annotator performance can be evaluated. Give the Dataset a meaningful name.

    <Tip> Learn how to create Datasets [here](/platform-documentation/Annotate/annotate-datasets/annotate-datasets).</Tip>
  </Step>

  <Step title="Create an Ontology">
    Create an Ontology to label your data. The same Ontology must be used in the Benchmark Project AND the Annotator Training Project.

    <Tip> Learn how to create Ontologies [here](/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies).</Tip>
  </Step>

  <Step title="Create the Benchmark Project">
    <Warning>
      Ensure that you attach ONLY the Training Dataset to the Project.
    </Warning>

    1. Go to **Annotate > Projects**.
    2. Click the **+ New annotation project** button to create a new Project.

    <div>
      <img />
    </div>

    3. Give the Project a meaningful title and description. For example "Benchmark Labels".
    4. Click the **Attach ontology** button and attach the Ontology you created.
    5. Click the **Attach dataset** button and attach the Benchmark Dataset you created.

    <div>
      <img />
    </div>

    7. Click **Create project** to finish creating the Project.
       You have now created the Project to establish ground-truth labels.
  </Step>
</Steps>

## STEP 3: Create Annotator Training Projects

Create a Project where your annotation workforce labels data and is evaluated against benchmark labels.

<Steps>
  <Step title="Create an Annotator Training Workflow Template">
    Create a Workflow template and give it a meaningful name like "Annotator Training".

    <Tip>Creating templates makes creating one Project per annotator quicker and easier.</Tip>

    Create the following Workflow template for your Annotator Training Projects. Documentation on how to create new Workflow templates can be found [here](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates).

    <div>
      <img />
    </div>
  </Step>

  <Step title="Create Annotator Training Projects">
    You must create one Annotator Training Project per annotator. Repeat this step for each annotator.

    <Warning>
      Ensure that you:

      * Attach the Training Dataset you created in **Step 2.1** for the Benchmark Project.
      * Attach the SAME Ontology you created in **Step 2.2** for the Benchmark Project.
      * Attach the Annotator Training Workflow Template to the Project.
    </Warning>

    1. Go to **Annotate > Projects**.
    2. Click the **+ New annotation project** button to create a new Project.
    3. Give the Project a meaningful title and description. For example "Annotator Training - Alex" for an annotator named Alex.
    4. Click the **Attach ontology** button and attach the Ontology you created. Attach the SAME Ontology you created in **Step 2.2** for the Benchmark Project.
    5. Click the **Attach dataset** button and attach the training Dataset you created in **Step 2.1**.
    6. Click the **Load from template** button to attach the "Annotator Training" template you created in **Step 3.1**.
    7. Click **Invite collaborators**. [Add the annotator](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate) you want to train in this Project to the annotation stage.
    8. Click **Create Project** to create the Project.
       You have now created the Project to train the selected annotator.

    <div>
      <img />
    </div>
  </Step>
</Steps>

## STEP 4: Annotator Training

Your annotators must now complete all tasks in the Annotator Training Project they are assigned to. Only tasks in the Complete stage are evaluated.

<Tip>
  Information on how to label can be found [here](/platform-documentation/GettingStarted/gettingstarted-labeling).
</Tip>

### Golden Label Reveal on Evaluation Tasks

Evaluation Projects that carry golden labels use a two-step submission flow to give annotators immediate feedback on their work.

**What are golden labels?**
Evaluation tasks store the correct answers alongside the annotator's work under ontology attributes prefixed with `golden_` (for example, `golden_detailed caption`, `golden_caption`). These attributes are invisible during annotation, so annotators label the task without seeing the correct answers.

**Two-step submission flow**

When an annotator clicks **Submit** on an evaluation task that contains golden labels, the editor does not submit the task immediately. Instead:

1. Read-only **Correct** rows appear beneath each timeline track, highlighted in green, showing the correct answers side by side with the annotator's labels.
2. A banner appears at the top of the editor reading: *"Correct labels revealed — compare with your answers, then confirm to submit."*
3. The annotator reviews their labels against the correct answers. Playback, zoom, and timeline seeking remain active so the annotator can compare answers in context.
4. The annotator clicks **Confirm & Submit** in the banner to complete the task.

<Note>
  All editing interactions lock during the reveal — hotkeys, drag and resize of timeline ranges, caption input, the options panel, the label bank, and dispatch controls are all disabled. Only playback and timeline navigation remain active.
</Note>

**Tasks without golden labels** submit immediately when the annotator clicks **Submit** — there is no change to the standard submission behavior.

<Warning>
  Submit-time validation (for example, missing required annotations or unresolved rejection issues) runs at the **Confirm & Submit** step, after editing is locked. If validation blocks submission at that point, the annotator cannot fix the task and must skip or reload. To avoid this, keep evaluation Ontologies free of required attributes.
</Warning>

## STEP 5: Evaluate Annotators

<Info>
  This example only evaluates Bounding Boxes.
</Info>

Save and run the following script to evaluate annotator performance. The script must be run once for each Annotator Training Project. It outputs a CSV file called `iou_results.csv` containing the results. The evaluation metrics used are Intersection over Union (IoU) and Class score.

<Info>
  * **IoU (Intersection over Union)**: Quantifies the overlap between predicted labels and the ground truth. It ranges from 0 to 1:
    1.0: Indicates a perfect overlap between the predicted label and the ground truth.
    0.0: Indicates no overlap between the predicted label and the ground truth.
    Values between 0 and 1: Represent the percentage of overlap. For example, an IoU of 0.6 signifies that 60% of the predicted label area overlaps with the ground truth label area.

  * **Class Score (0 or 1)**:
    1: The label was created using the correct class.
    0: The label was created using the wrong class.
</Info>

Ensure that you:

* Replace `<private_key_path>` with the full path to your private access key.
* Replace `<benchmark-project-id>` with the id of your Benchmark Project.
* Replace `<training-project-id>` with the id of the Training Project you want to evaluate.

<CodeGroup>
  ```python Annotator Training Evaluation theme={"dark"}
  from encord import EncordUserClient
  from encord.objects.common import Shape
  from encord.objects.coordinates import BoundingBoxCoordinates
  import pandas as pd
  from encord.user_client import EncordUserClient
  import os

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  training_project_id = "<training-project-id>"
  benchmark_project_id = "<benchmark-project-id>"

  training_project = user_client.get_project(training_project_id)
  benchmark_project = user_client.get_project(benchmark_project_id)

  training_label_rows = training_project.list_label_rows_v2(workflow_graph_node_title_eq='Complete')
  benchmark_label_rows = benchmark_project.list_label_rows_v2(workflow_graph_node_title_eq='Complete')

  # Match by data_hash
  benchmark_dict = {lr.data_hash: lr for lr in benchmark_label_rows}
  paired_label_rows = [
      (benchmark_dict[lr.data_hash], lr)
      for lr in training_label_rows
      if lr.data_hash in benchmark_dict
  ]

  # Initialize labels
  with training_project.create_bundle() as bundle:
      for _, prod_lr in paired_label_rows:
          prod_lr.initialise_labels(bundle=bundle, overwrite=True)

  with benchmark_project.create_bundle() as bundle:
      for bm_lr, _ in paired_label_rows:
          bm_lr.initialise_labels(bundle=bundle, overwrite=True)

  # IoU calculation
  def calculate_iou(bbox1: BoundingBoxCoordinates, bbox2: BoundingBoxCoordinates) -> float:
      x_left = max(bbox1.top_left_x, bbox2.top_left_x)
      y_top = max(bbox1.top_left_y, bbox2.top_left_y)
      x_right = min(bbox1.top_left_x + bbox1.width, bbox2.top_left_x + bbox2.width)
      y_bottom = min(bbox1.top_left_y + bbox1.height, bbox2.top_left_y + bbox2.height)
      intersection = max(0, x_right - x_left) * max(0, y_bottom - y_top)
      union = bbox1.width * bbox1.height + bbox2.width * bbox2.height - intersection
      return intersection / union if union > 0 else 0.0

  # Compare labels and extract information
  results = []
  for bm_lr, prod_lr in paired_label_rows:
      prod_instances = [oi for oi in prod_lr.get_object_instances() if oi.ontology_item.shape == Shape.BOUNDING_BOX and oi.get_annotation(0)]
      bm_instances = [oi for oi in bm_lr.get_object_instances() if oi.ontology_item.shape == Shape.BOUNDING_BOX and oi.get_annotation(0)]

      training_data_unit_name = prod_lr.data_title
      training_label_id = prod_lr.label_hash

      for prod_obj in prod_instances:
          best_iou = 0.0
          best_match_hash = None
          prod_bbox = prod_obj.get_annotation(0).coordinates
          training_email = prod_obj.get_annotation(0).created_by

          for bm_obj in bm_instances:
              bm_bbox = bm_obj.get_annotation(0).coordinates
              iou = calculate_iou(prod_bbox, bm_bbox)
              if iou > best_iou:
                  best_iou = iou
                  best_match_hash = bm_obj.feature_hash

          class_score = 1.0 if best_match_hash == prod_obj.feature_hash and best_match_hash is not None else 0.0

          results.append({
              'training_email': training_email,
              'data_unit_name': training_data_unit_name,
              'label_id': training_label_id,
              'iou_score': best_iou,
              'class_score': class_score
          })

  # Output the results to a CSV file
  if results:
      df_results = pd.DataFrame(results)
      script_dir = os.path.dirname(os.path.abspath(__file__))
      csv_file_path = os.path.join(script_dir, "iou_results.csv")
      df_results.to_csv(csv_file_path, index=False)
      print(f"Results saved to: {csv_file_path}")
  else:
      print("No matching label rows found for comparison.")
  ```

  ```csv Example Output theme={"dark"}
  training_email,data_unit_name,label_id,iou_score,class_score
  david.babuschkin@encord.com,Image3.jpg,a4a3d707-e077-47f1-9bad-d05a1fcc28aa,0.0,0.0
  david.babuschkin@encord.com,Image6.jpg,be53b547-7a5e-4476-9018-903ce7ad4d99,0.5506647634569868,1.0
  ```
</CodeGroup>


# Automated QA Workflow
Source: https://docs.encord.com/end-to-end/BenchmarkQA/automated-qa



To set up a Benchmark QA Workflow, you need to create two distinct Projects:

* **Benchmark Project:** This Project establishes the "ground-truth" labels, which serve as the benchmark for evaluating annotator performance.
* **Production Project:** In this Project, annotators generate the production labels. Annotator performance is scored against the ground-truth labels from the first Project.

***

## STEP 1: Register Files with Encord

You must first register your files with Encord. This includes files that are used to establish 'ground-truth' labels, and your production data.

<Steps>
  <Step title="Create a Cloud Integration">
    Select your cloud provider:

    <div lang="en">
      <head>
        <meta />

        <meta name="viewport" />

        <title>Clickable Div</title>
      </head>

      <div>
        <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration">
          AWS Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration">
          GCP Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration">
          Azure Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-otc-integration">
          OTC Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-wasabi-integration">
          Wasabi Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-oracle-integration">
          Oracle Integration
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-direct-access-integration">
          Direct Access Integration
        </a>
      </div>
    </div>
  </Step>

  <Step title="Create a Folder to Store your Files">
    1. Navigate to **Data** > **Files & Folders**
    2. Click the **+ New folder** button to create a new folder. Select the type of folder you want to create.

    <div>
      <img />
    </div>

    3. Give the folder a meaningful name and description.

    4. Click **Create** to create the folder.
       The folder is listed in **Files & Folders**.
  </Step>

  <Step title="Create JSON file for Registration">
    To register files from cloud storage into Encord, you must create a JSON file specifying the files you want to upload.

    <Info>
      While you can [use a CSV file](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format), we strongly recommend using JSON files for uploading cloud data to Encord for better compatibility and performance.
    </Info>

    <Tip>
      Find helpful scripts for creating JSON files for the data registration process [here](/platform-documentation/Curate/add-files/index-register-cloud-data#helpful-scripts-and-examples).
    </Tip>

    All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

    <Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data)</Note>

    <Info>Encord supports file names up to 300 characters in length for any file or video for upload.</Info>

    <Info>
      Encord enforces the following upload limits for each JSON file used for file registration:

      * Up to 1 million URLs
      * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
      * URLs can be up to 16 KB in size

      Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
    </Info>

    <Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

    <AccordionGroup>
      <Accordion title="JSON Format">
        For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

        The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

        <Note>If `skip_duplicate_urls` is set to `true`, all object URLs that exactly match existing images/videos in the dataset are skipped.</Note>

        <Accordion title="JSON for AWS">
          <AccordionGroup>
            <Accordion title="Videos">
              #### [Videos](#videos)

              **Video Metadata**

              When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

              <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "cloud-path-to-your-video-1"
                    },
                    {
                      "objectUrl": "cloud-path-to-your-video-2",
                        "videoMetadata": {
                          "fps": frames-per-second,
                          "duration": duration-in-seconds,
                          "width": frame-width,
                          "height": frame-height,
                          "file_size": file-size-in-bytes,
                          "mime_type": "MIME-file-type-extension"
                        }
                      }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/BerghouseLeopardJog.mp4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blue_bus_video.mp4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/bluemlisalphutte_flyover.mp4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake_normalized.mp4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/snow_sled.MOV"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cyclists.MP4"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Video Metadata theme={"dark"}
                {
                    "videos": [
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/video_file.mp4",
                        "videoMetadata": {
                            "fps": 23.98,
                            "duration": 29.09,
                            "width": 1280,
                            "height": 720,
                            "file_size": 5468354,
                            "mime_type": "video/mp4"
                        }
                      }
                    ],
                  "skip_duplicate_urls": true
                  }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Audio files">
              #### [Audio Files](#audio-files)

              The following is an example JSON file for uploading two audio files to Encord.

              <Tip>
                Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
              </Tip>

              * **Template:** Imports audio files with an Encord title.
              * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "audio": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-custom-audio-file-title.mp3"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Audio Metadata theme={"dark"}
                {
                    "audio": [
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file.mp3",
                        "audioMetadata": {
                            "duration": 23.98,
                            "file_size": 2900000,
                            "mime_type": "audio/mp3",
                            "sample_rate": 44100,
                            "bit_depth": 24,
                            "codec": "mp3",
                            "num_channels": 2
                        }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="PDFs">
              #### [PDFs](#pdfs)

              The following are example JSON files for uploading PDFs to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "pdfs": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-document-02.pdf"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-document-03.pdf",
                      "pdfMetadata": {
                        "fileSize": 300,
                        "numPages": 5
                        }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "pdfs": [
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-01.pdf",

                      },
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-02.pdf",
                        "title": "my-document-02.pdf"
                      },
                      {
                        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-03.pdf",
                        "title": "my-document-03.pdf",
                        "pdfMetadata": {
                          "fileSize": 300,
                          "numPages": 5
                          }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Text Files">
              #### [Text Files](#text-files)

              The following are example JSON files for uploading text files to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "text": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-file.html"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-plain-text-file.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "<object url_4>",
                      "title": "my-csv-file.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "<object url_5>",
                      "title": "my-xml-file.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "<object url_6>",
                      "title": "my-html-file.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "text": [
                      {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-file-01.html"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-01.txt",
                      "title": "my-plain-text-file-01.txt"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-02.txt",
                      "title": "my-plain-text-file-02.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-csv-file-01.csv",
                      "title": "my-csv-file-01.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-xml-file-01.xml",
                      "title": "my-xml-file-01.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-html-file-01.html",
                      "title": "my-html-file-01.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Single images">
              #### [Single Images](#single-images)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              The JSON structure for single images parallels that of videos.

              **Template:** Provides the proper JSON format to import images into Encord.

              **Examples:**

              * **Data** Imports the images only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "file/path/to/images/file-name-01.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-02.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-03.file-extension",
                      "title": "image-title.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data    theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.jpg"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0003.jpg"
                    },
                    {
                      "objectUrl": "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"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                    },
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/large_images/pexels-ivo-rainha-00057.png"
                    }
                  ]
                }
                ```

                ```json Image Metadata theme={"dark"}

                {
                  "images": [
                    {
                      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/my_image.jpg",
                      "imageMetadata": {
                        "mimeType": "image/jpg",
                        "fileSize": 124,
                        "width": 640,
                        "height": 480
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image groups">
              #### [Image groups](#image-groups)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image groups are collections of images that are processed as one annotation task.
              * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
              * Image groups do NOT require 'write' permissions to your cloud storage.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the image groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "image_groups": [
                    {
                      "title": "<title 1>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                    },
                    {
                      "title": "<title 2>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image group 01",
                      "createVideo": false,
                      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg",
                      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.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 group 02",
                      "createVideo": false,
                      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0001.jpg",
                      "objectUrl_1": "<https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0002.jpg",
                      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0003.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image sequences">
              #### [Image sequences](#image-sequences)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image sequences are collections of images that are processed as one annotation task and represented as a video.
              * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
              * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
              * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

              <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the images groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "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>"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "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
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="DICOM">
              #### [DICOM](#dicom)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Each `dicom_series` element can contain one or more DICOM series.
              * Each series requires a title and at least one object URL, as shown in the example below.
              * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

              <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

              The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

              * The first series contains only a single object URL, as it is composed of a single file.
              * The second series contains 3 object URLs, as it is composed of three separate files.
              * The third series contains 2 object URLs, as it is composed of two separate files.

              <Info>
                For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
              </Info>

              ```json Template theme={"dark"}
              {
                "dicom_series": [
                  {
                    "title": "Series-1",
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series1-file.dcm"
                  },
                  {
                    "title": "Series-2",
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file1.dcm",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file2.dcm",
                    "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file3.dcm",
                  },
                    {
                    "title": "Series-3",
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file1.dcm",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file2.dcm",
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="NIfTI">
              #### [NIfTI](#nifti)

              The following is an example JSON file for uploading two NIfTI files to Encord.

              ```json Template theme={"dark"}
              {
                  "nifti": [
                    {
                      "title": "<file-1>",
                      "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                    },
                    {
                      "title": "<file-2>",
                      "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title=" Multiple file types ">
              You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

              ```json Multiple file types theme={"dark"}

              {
                "images": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/Image1.png"
                  }
                ],
                "videos": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Cooking.mp4"
                  },
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Oranges.mp4"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-samsung-light",
                    "createVideo": true,
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(32).jpg",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
                    "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
                    "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
                  },
                  {
                    "title": "apple-samsung-dark",
                    "createVideo": true,
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(32).jpg",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(33).jpg",
                    "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(34).jpg",
                    "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(35).jpg"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-ios-light",
                    "createVideo": false,
                    "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(32).jpg",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(33).jpg"
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>
        </Accordion>

        <Accordion title="JSON for GCP">
          <AccordionGroup>
            <Accordion title="Videos">
              #### [Videos](#videos)

              **Video Metadata**

              When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

              <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "cloud-path-to-your-video-1"
                    },
                    {
                      "objectUrl": "cloud-path-to-your-video-2",
                        "videoMetadata": {
                          "fps": frames-per-second,
                          "duration": duration-in-seconds,
                          "width": frame-width,
                          "height": frame-height,
                          "file_size": file-size-in-bytes,
                          "mime_type": "MIME-file-type-extension"
                        }
                      }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/eLeopardJog.mp4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/_video.mp4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/bluemlisalphutte_flyover.mp4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake_normalized.mp4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/snow_sled.MOV"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/cyclists.MP4"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Video Metadata theme={"dark"}
                {
                    "videos": [
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/video_file.mp4",
                        "videoMetadata": {
                            "fps": 23.98,
                            "duration": 29.09,
                            "width": 1280,
                            "height": 720,
                            "file_size": 5468354,
                            "mime_type": "video/mp4"
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                  }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Audio files">
              #### [Audio Files](#audio-files)

              The following is an example JSON file for uploading two audio files to Encord.

              <Tip>
                Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
              </Tip>

              * Example 1 imports audio files with an Encord title.
              * Example 2 imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "audio": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-custom-audio-file-title.mp3"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Audio Metadata theme={"dark"}
                {
                    "audio": [
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/audio_file.mp3",
                        "audioMetadata": {
                            "duration": 23.98,
                            "file_size": 2900000,
                            "mime_type": "audio/mp3",
                            "sample_rate": 44100,
                            "bit_depth": 24,
                            "codec": "mp3",
                            "num_channels": 2
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="PDFs">
              #### [PDFs](#pdfs)

              The following are example JSON files for uploading PDFs to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "pdfs": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-document-02.pdf"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-document-03.pdf",
                      "pdfMetadata": {
                        "fileSize": 300,
                        "numPages": 5
                        }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "pdfs": [
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-01.pdf",

                      },
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-02.pdf",
                        "title": "my-document-02.pdf"
                      },
                      {
                        "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-03.pdf",
                        "title": "my-document-03.pdf",
                        "pdfMetadata": {
                          "fileSize": 300,
                          "numPages": 5
                          }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Text Files">
              #### [Text Files](#text-files)

              The following are example JSON files for uploading text files to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "text": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-file.html"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-plain-text-file.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "<object url_4>",
                      "title": "my-csv-file.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "<object url_5>",
                      "title": "my-xml-file.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "<object url_6>",
                      "title": "my-html-file.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "text": [
                      {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-file-01.html"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-01.txt",
                      "title": "my-plain-text-file-01.txt"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-02.txt",
                      "title": "my-plain-text-file-02.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-csv-file-01.csv",
                      "title": "my-csv-file-01.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-xml-file-01.xml",
                      "title": "my-xml-file-01.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-html-file-01.html",
                      "title": "my-html-file-01.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Single images">
              #### [Single Images](#single-images)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              The JSON structure for single images parallels that of videos.

              **Template:** Provides the proper JSON format to import images into Encord.

              **Examples:**

              * **Data** Imports the images only.

              * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "file/path/to/images/file-name-01.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-02.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-03.file-extension",
                      "title": "image-title.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/0001.jpg"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0003.jpg"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                    },
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/large_images/pexels-ivo-rainha-00057.png"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Image Metadata theme={"dark"}

                {
                  "images": [
                    {
                      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/my_image.jpg",
                      "imageMetadata": {
                        "mimeType": "image/jpg",
                        "fileSize": 124,
                        "width": 640,
                        "height": 480
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image groups">
              #### [Image groups](#image-groups)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image groups are collections of images that are processed as one annotation task.
              * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
              * Image groups do NOT require 'write' permissions to your cloud storage.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the image groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "image_groups": [
                    {
                      "title": "<title 1>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                    },
                    {
                      "title": "<title 2>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image group 01",
                      "createVideo": false,
                      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/0001.jpg",
                      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg",
                      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "title": "Image group 02",
                      "createVideo": false,
                      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0001.jpg",
                      "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-0002.jpg",
                      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0003.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image sequences">
              #### [Image sequences](#image-sequences)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image sequences are collections of images that are processed as one annotation task and represented as a video.
              * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
              * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
              * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

              <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the images groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "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>"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image sequence 001",
                      "createVideo": true,
                      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/01.jpg",
                      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/02.jpg",
                      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/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://storage.cloud.google.com/encord-image-bucket/images/thing-01.jpg",
                      "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-02.jpg",
                      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-03.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="DICOM">
              #### [DICOM](#dicom)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Each `dicom_series` element can contain one or more DICOM series.
              * Each series requires a title and at least one object URL, as shown in the example below.
              * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

              <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

              The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

              * The first series contains only a single object URL, as it is composed of a single file.
              * The second series contains 3 object URLs, as it is composed of three separate files.
              * The third series contains 2 object URLs, as it is composed of two separate files.

              <Info>
                For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
              </Info>

              ```json JSON for DICOM theme={"dark"}
              {
                "dicom_series": [
                  {
                    "title": "Series-1",
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series1-file.dcm"
                  },
                  {
                    "title": "Series-2",
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file1.dcm",
                    "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file2.dcm",
                    "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file3.dcm",
                  },
                    {
                    "title": "Series-3",
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file1.dcm",
                    "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file2.dcm",
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="NIfTI">
              #### [NIfTI](#nifti)

              The following is an example JSON file for uploading two NIfTI files to Encord.

              ```json theme={"dark"}
              {
                  "nifti": [
                    {
                      "title": "<file-1>",
                      "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                    },
                    {
                      "title": "<file-2>",
                      "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title=" Multiple file types ">
              You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

              ```json Multiple file types theme={"dark"}

              {
                "images": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/Image1.png"
                  }
                ],
                "videos": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Cooking.mp4"
                  },
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Oranges.mp4"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-samsung-light",
                    "createVideo": true,
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/1+(32).jpg",
                    "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
                    "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
                    "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
                  },
                  {
                    "title": "apple-samsung-dark",
                    "createVideo": true,
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/2+(32).jpg",
                    "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/2+(33).jpg",
                    "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/2+(34).jpg",
                    "objectUrl_3": "https://storage.cloud.google.com/encord-image-bucket/images/2+(35).jpg"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-ios-light",
                    "createVideo": false,
                    "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/3+(32).jpg",
                    "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/3+(33).jpg"
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>
        </Accordion>

        <Accordion title="JSON for Azure">
          <AccordionGroup>
            <Accordion title="Videos">
              #### [Videos](#videos)

              **Video Metadata**

              When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

              <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "cloud-path-to-your-video-1"
                    },
                    {
                      "objectUrl": "cloud-path-to-your-video-2",
                        "videoMetadata": {
                          "fps": frames-per-second,
                          "duration": duration-in-seconds,
                          "width": frame-width,
                          "height": frame-height,
                          "file_size": file-size-in-bytes,
                          "mime_type": "MIME-file-type-extension"
                        }
                      }
                    {
                      "objectUrl": "cloud-path-to-your-video-3",
                      "title": "title-for-your-video-3"

                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/BerghouseLeopardJog.mp4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/blue_bus_video.mp4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/bluemlisalphutte_flyover.mp4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake_normalized.mp4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/snow_sled.MOV"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/cyclists.MP4"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Video Metadata theme={"dark"}
                {
                    "videos": [
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/video_file.mp4",
                        "videoMetadata": {
                            "fps": 23.98,
                            "duration": 29.09,
                            "width": 1280,
                            "height": 720,
                            "file_size": 5468354,
                            "mime_type": "video/mp4"
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                  }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Audio files">
              #### [Audio Files](#audio-files)

              The following is an example JSON file for uploading two audio files to Encord.

              <Tip>
                Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
              </Tip>

              * **Template:** Imports audio files with an Encord title.
              * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "audio": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-custom-audio-file-title.mp3"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Audio Metadata theme={"dark"}
                {
                    "audio": [
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/audio_file.mp3",
                        "audioMetadata": {
                            "duration": 23.98,
                            "file_size": 2900000,
                            "mime_type": "audio/mp3",
                            "sample_rate": 44100,
                            "bit_depth": 24,
                            "codec": "mp3",
                            "num_channels": 2
                        }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="PDFs">
              #### [PDFs](#pdfs)

              The following are example JSON files for uploading PDFs to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "pdfs": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-document-02.pdf"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-document-03.pdf",
                      "pdfMetadata": {
                        "fileSize": 300,
                        "numPages": 5
                        }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "pdfs": [
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-01.pdf",

                      },
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-02.pdf",
                        "title": "my-document-02.pdf"
                      },
                      {
                        "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-03.pdf",
                        "title": "my-document-03.pdf",
                        "pdfMetadata": {
                          "fileSize": 300,
                          "numPages": 5
                          }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Text Files">
              #### [Text Files](#text-files)

              The following are example JSON files for uploading text files to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "text": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-file.html"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-plain-text-file.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "<object url_4>",
                      "title": "my-csv-file.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "<object url_5>",
                      "title": "my-xml-file.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "<object url_6>",
                      "title": "my-html-file.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "text": [
                      {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-file-01.html"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-01.txt",
                      "title": "my-plain-text-file-01.txt"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-02.txt",
                      "title": "my-plain-text-file-02.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-csv-file-01.csv",
                      "title": "my-csv-file-01.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-xml-file-01.xml",
                      "title": "my-xml-file-01.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-html-file-01.html",
                      "title": "my-html-file-01.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Single images">
              #### [Single Images](#single-images)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              The JSON structure for single images parallels that of videos.

              **Template:** Provides the proper JSON format to import images into Encord.

              **Examples:**

              * **Data** Imports the images only.

              * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "file/path/to/images/file-name-01.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-02.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-03.file-extension",
                      "title": "image-title.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0003.jpg"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                    },
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/large_images/pexels-ivo-rainha-00057.png"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Image Metadata theme={"dark"}

                {
                  "images": [
                    {
                      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my_image.jpg",
                      "imageMetadata": {
                        "mimeType": "image/jpg",
                        "fileSize": 124,
                        "width": 640,
                        "height": 480
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image groups">
              #### [Image groups](#image-groups)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image groups are collections of images that are processed as one annotation task.
              * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
              * Image groups do NOT require 'write' permissions to your cloud storage.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the image groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "image_groups": [
                    {
                      "title": "<title 1>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                    },
                    {
                      "title": "<title 2>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image group 01",
                      "createVideo": false,
                      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg",
                      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg",
                      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "title": "Image group 02",
                      "createVideo": false,
                      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0001.jpg",
                      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0002.jpg",
                      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-0003.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image sequences">
              #### [Image sequences](#image-sequences)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image sequences are collections of images that are processed as one annotation task and represented as a video.
              * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
              * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
              * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

              <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the images groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "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>"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image sequence 001",
                      "createVideo": true,
                      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/01.jpg",
                      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/02.jpg",
                      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/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://myaccount.blob.core.windows.net/encordcontainer/thing-01.jpg",
                      "objectUrl_1": "<https://myaccount.blob.core.windows.net/encordcontainer/thing-02.jpg",
                      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-03.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="DICOM">
              #### [DICOM](#dicom)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Each `dicom_series` element can contain one or more DICOM series.
              * Each series requires a title and at least one object URL, as shown in the example below.
              * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

              <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

              The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

              * The first series contains only a single object URL, as it is composed of a single file.
              * The second series contains 3 object URLs, as it is composed of three separate files.
              * The third series contains 2 object URLs, as it is composed of two separate files.

              <Info>
                For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
              </Info>

              ```json Template theme={"dark"}
              {
                "dicom_series": [
                  {
                    "title": "Series-1",
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series1-file.dcm"
                  },
                  {
                    "title": "Series-2",
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file1.dcm",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file2.dcm",
                    "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file3.dcm",
                  },
                    {
                    "title": "Series-3",
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file1.dcm",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file2.dcm",
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="NIfTI">
              #### [NIfTI](#nifti)

              The following is an example JSON file for uploading two NIfTI files to Encord.

              ```json Template theme={"dark"}
              {
                  "nifti": [
                    {
                      "title": "<file-1>",
                      "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                    },
                    {
                      "title": "<file-2>",
                      "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title=" Multiple file types ">
              You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

              ```json theme={"dark"}

              {
                "images": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Image1.png"
                  }
                ],
                "videos": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Cooking.mp4"
                  },
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Oranges.mp4"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-samsung-light",
                    "createVideo": true,
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(32).jpg",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(33).jpg",
                    "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(34).jpg",
                    "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(35).jpg"
                  },
                  {
                    "title": "apple-samsung-dark",
                    "createVideo": true,
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(32).jpg",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(33).jpg",
                    "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(34).jpg",
                    "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(35).jpg"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-ios-light",
                    "createVideo": false,
                    "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(32).jpg",
                    "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(33).jpg"
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>
        </Accordion>

        <Accordion title="JSON for OTC">
          <AccordionGroup>
            <Accordion title="Videos">
              #### [Videos](#videos)

              **Video Metadata**

              When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

              <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "cloud-path-to-your-video-1"
                    },
                    {
                      "objectUrl": "cloud-path-to-your-video-2",
                        "videoMetadata": {
                          "fps": frames-per-second,
                          "duration": duration-in-seconds,
                          "width": frame-width,
                          "height": frame-height,
                          "file_size": file-size-in-bytes,
                          "mime_type": "MIME-file-type-extension"
                        }
                      }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "videos": [
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/og.mp4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/blue_bus_video.mp4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/bluemlisalphutte_flyover.mp4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake_normalized.mp4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/snow_sled.MOV"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/cyclists.MP4"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Video Metadata theme={"dark"}
                {
                    "videos": [
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/video_file.mp4",
                        "videoMetadata": {
                            "fps": 23.98,
                            "duration": 29.09,
                            "width": 1280,
                            "height": 720,
                            "file_size": 5468354,
                            "mime_type": "video/mp4"
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                  }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Audio files">
              #### [Audio Files](#audio-files)

              The following is an example JSON file for uploading two audio files to Encord.

              <Tip>
                Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
              </Tip>

              * **Template:**  Imports audio files with an Encord title.
              * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "audio": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-custom-audio-file-title.mp3"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Audio Metadata theme={"dark"}
                {
                    "audio": [
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/audio/audio_file.mp3",
                        "audioMetadata": {
                            "duration": 23.98,
                            "file_size": 2900000,
                            "mime_type": "audio/mp3",
                            "sample_rate": 44100,
                            "bit_depth": 24,
                            "codec": "mp3",
                            "num_channels": 2
                        }
                      }
                    ],
                    "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="PDFs">
              #### [PDFs](#pdfs)

              The following are example JSON files for uploading PDFs to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "pdfs": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-document-02.pdf"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-document-03.pdf",
                      "pdfMetadata": {
                        "fileSize": 300,
                        "numPages": 5
                        }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "pdfs": [
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-01.pdf",

                      },
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-02.pdf",
                        "title": "my-document-02.pdf"
                      },
                      {
                        "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-3.pdf",
                        "title": "my-document-03.pdf",
                        "pdfMetadata": {
                          "fileSize": 300,
                          "numPages": 5
                          }
                      }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Text Files">
              #### [Text Files](#text-files)

              The following are example JSON files for uploading text files to Encord.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "text": [
                    {
                      "objectUrl": "<object url_1>"
                    },
                    {
                      "objectUrl": "<object url_2>",
                      "title": "my-file.html"
                    },
                    {
                      "objectUrl": "<object url_3>",
                      "title": "my-plain-text-file.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "<object url_4>",
                      "title": "my-csv-file.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "<object url_5>",
                      "title": "my-xml-file.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "<object url_6>",
                      "title": "my-html-file.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                    "text": [
                      {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-file-01.html"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-01.txt",
                      "title": "my-plain-text-file-01.txt"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-02.txt",
                      "title": "my-plain-text-file-02.txt",
                      "textMetadata": {
                        "fileSize": 200,
                        "mime_type": "text/plain"
                      }
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-csv-file-01.csv",
                      "title": "my-csv-file-01.csv",
                      "textMetadata": {
                        "fileSize": 250,
                        "mime_type": "text/csv"
                      }
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-xml-file-01.xml",
                      "title": "my-xml-file-01.xml",
                      "textMetadata": {
                        "fileSize": 300,
                        "mime_type": "application/xml"
                      }
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-html-file-01.html",
                      "title": "my-html-file-01.html",
                      "textMetadata": {
                        "fileSize": 400,
                        "mime_type": "text/html"
                      }
                    }
                    ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Single images">
              #### [Single Images](#single-images)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              The JSON structure for single images parallels that of videos.

              **Template:** Provides the proper JSON format to import images into Encord.

              **Examples:**

              * **Data** Imports the images only.

              * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "file/path/to/images/file-name-01.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-02.file-extension"
                    },
                    {
                      "objectUrl": "file/path/to/images/file-name-03.file-extension",
                      "title": "image-title.file-extension"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}
                {
                  "images": [
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0003.jpg"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                    },
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/large_images/pexels-ivo-rainha-00057.png"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Image Metadata theme={"dark"}

                {
                  "images": [
                    {
                      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my_image.jpg",
                      "imageMetadata": {
                        "mimeType": "image/jpg",
                        "fileSize": 124,
                        "width": 640,
                        "height": 480
                      }
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image groups">
              #### [Image groups](#image-groups)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image groups are collections of images that are processed as one annotation task.
              * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
              * Image groups do NOT require 'write' permissions to your cloud storage.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the image groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "image_groups": [
                    {
                      "title": "<title 1>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                    },
                    {
                      "title": "<title 2>",
                      "createVideo": false,
                      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                      "clientMetadata": {"optional": "metadata"}
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image group 01",
                      "createVideo": false,
                      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg",
                      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg",
                      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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 group 02",
                      "createVideo": false,
                      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0001.jpg",
                      "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0002.jpg",
                      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0003.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="Image sequences">
              #### [Image sequences](#image-sequences)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Image sequences are collections of images that are processed as one annotation task and represented as a video.
              * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
              * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
              * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
              * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

              <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

              <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

              <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

              **Template:** Provides the proper JSON format to import image groups into Encord.

              **Examples:**

              * **Data:** Imports the images groups only.

              <CodeGroup>
                ```json Template theme={"dark"}
                {
                  "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>"
                    }
                  ],
                  "skip_duplicate_urls": true
                }
                ```

                ```json Data theme={"dark"}

                {
                  "image_groups": [
                    {
                      "title": "Image sequence 001",
                      "createVideo": true,
                      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/01.jpg",
                      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/02.jpg",
                      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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-bucket.obs.eu-de.otc.t-systems.com/images/thing-01.jpg",
                      "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-02.jpg",
                      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-03.jpg"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

                ```
              </CodeGroup>
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="DICOM">
              #### [DICOM](#dicom)

              For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

              * Each `dicom_series` element can contain one or more DICOM series.
              * Each series requires a title and at least one object URL, as shown in the example below.
              * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

              <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

              The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

              * The first series contains only a single object URL, as it is composed of a single file.
              * The second series contains 3 object URLs, as it is composed of three separate files.
              * The third series contains 2 object URLs, as it is composed of two separate files.

              <Info>
                For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
              </Info>

              ```json JSON for DICOM theme={"dark"}
              {
                "dicom_series": [
                  {
                    "title": "Series-1",
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series1-file.dcm"
                  },
                  {
                    "title": "Series-2",
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file1.dcm",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file2.dcm",
                    "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file3.dcm",
                  },
                    {
                    "title": "Series-3",
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file1.dcm",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file2.dcm",
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title="NIfTI">
              #### [NIfTI](#nifti)

              The following is an example JSON file for uploading two NIfTI files to Encord.

              ```json theme={"dark"}
              {
                  "nifti": [
                    {
                      "title": "<file-1>",
                      "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                    },
                    {
                      "title": "<file-2>",
                      "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                    }
                  ],
                  "skip_duplicate_urls": true
                }

              ```
            </Accordion>
          </AccordionGroup>

          <AccordionGroup>
            <Accordion title=" Multiple file types ">
              You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

              ```json Multiple file types theme={"dark"}

              {
                "images": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/Image1.png"
                  }
                ],
                "videos": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Cooking.mp4"
                  },
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Oranges.mp4"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-samsung-light",
                    "createVideo": true,
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(32).jpg",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(33).jpg",
                    "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(34).jpg",
                    "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(35).jpg"
                  },
                  {
                    "title": "apple-samsung-dark",
                    "createVideo": true,
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(32).jpg",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(33).jpg",
                    "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(34).jpg",
                    "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(35).jpg"
                  }
                ],
                "image_groups": [
                  {
                    "title": "apple-ios-light",
                    "createVideo": false,
                    "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(32).jpg",
                    "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(33).jpg"
                  }
                ],
                "skip_duplicate_urls": true
              }

              ```
            </Accordion>
          </AccordionGroup>
        </Accordion>

        <Accordion title="JSON for AWS Multi-Region Access Point">
          When using a Multi-Region Access Point for your AWS S3 buckets the JSON file has to be slightly different from the examples provided. Instead of an object's URL, objects are specified using the ARN of the Multi-Region Access Point followed by the object name. The example below shows how video files from a Multi-Region Access Point would be specified.

          ```json theme={"dark"}
          {
            "videos": [
              {
                "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
              },
              {
                "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
                "title": "my-custom-video-title.mp4"
              }
            ],
            "skip_duplicate_urls": true
          }
          ```

          ```json MRAP Example theme={"dark"}
          {
            "videos": [
              {
                "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_1.mp4"
              },
              {
                "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_2.mp4",
                "title": "many-cute-cats.mp4"
              }
            ],
            "skip_duplicate_urls": true
          }
          ```
        </Accordion>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Import your Files">
    <AccordionGroup>
      <Accordion title="Import cloud data">
        <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

        1. Navigate to **Data** > **Files & Folders** in the Encord platform.
        2. Click into a Folder.
        3. Click **+ Upload files**.
           A dialog appears.

        <div>
          <img />
        </div>

        4. Click **Import from cloud data**.

        <div>
          <img />
        </div>

        <Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

        6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Import local data">
        <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

        1. Navigate to **Data** > **Files & Folders** in the Encord platform.
        2. Click into a Folder.
        3. Click **+ Upload files**.
           A dialog appears.

        <img />

        4. Click one of the following:
           * **Upload:** Upload images, videos, and audio files.
             ![Upload dialog](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-001.png)
           * **Batch images as:** Upload image batches as image groups or image sequences.
             ![Batch images as](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-02.png)
           * **DICOM/NifTi:** Upload DICOM or NifTi series.
             ![DICOM/NifTi](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-03.png)

        5. Click **Upload** after selecting your images or series.

           Your files upload into the Folder in Encord.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## STEP 2: Create Benchmark Project

The Benchmark Project establishes ground truth labels.

<Steps>
  <Step title="Create a Benchmark Dataset">
    Create a Dataset containing tasks designed to establish ground truth labels. These files will be used to generate 'gold-standard' labels against which annotator performance will be evaluated. Be sure to give the Dataset a clear and descriptive name.

    <Tip> Learn how to create Datasets [here](/platform-documentation/Annotate/annotate-datasets/annotate-datasets)</Tip>
  </Step>

  <Step title="Create an Ontology">
    Create an Ontology to label your data. The same Ontology is used in the Benchmark Project AND the Production Project.

    <Tip> Learn how to create Ontologies [here](/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies)</Tip>
  </Step>

  <Step title="Create a Workflow Template">
    Create a Workflow template to establish ground truth labels and give it a meaningful name like "Establishing Benchmarks". The following example template is just one approach; however, the process for creating benchmark labels is flexible, allowing you to choose any Workflow that suits your requirements.

    <Tip>For information on how to create Workflow templates see our [documentation here](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates).</Tip>

    <div>
      <img />
    </div>
  </Step>

  <Step title="Create the Benchmark Project">
    <Warning>
      Ensure that you:

      * Attach ONLY the Benchmark Dataset to the Project.
      * Attach the Benchmark Workflow Template to the Project.
    </Warning>

    1. In the Encord platform, navigate to **Projects**.
    2. Click the **+ New annotation project** button to create a new Project.

    <div>
      <img />
    </div>

    3. Give the Project a meaningful title and description, for example "Benchmark Labels".
    4. Click the **Attach ontology** button and attach the Ontology you created.
    5. Click the **Attach dataset** button and attach the Dataset you created.
    6. Click the **Load from template** button to attach the template you created in **STEP 2.3**.

    <div>
      <img />
    </div>

    7. Click **Create project** to finish creating the Project.
       You have now created the Project to establish ground-truth labels.
  </Step>
</Steps>

## STEP 3: Create Benchmark Labels

Complete the Benchmark Project created in **STEP 2** to establish a set of ground truth labels for all data units in the Benchmark Dataset.

<Tip>To learn how to create annotations, see our [documentation here](/platform-documentation/GettingStarted/gettingstarted-labeling).</Tip>

## STEP 4: Create Production Project

Create a Project where your annotation workforce labels data and is evaluated against benchmark labels.

<Steps>
  <Step title="Create a Production Dataset">
    Create a Dataset using your Production data. Give the Dataset a meaningful name and description to distinguish it from the Benchmark Dataset created in STEP 2.
  </Step>

  <Step title="Create a Production Workflow Template">
    Create a Workflow template for labeling production data using Benchmark QA and give it a meaningful name like "Benchmark QA Production Labels"

    The following Workflow template is an example showing how to set up a Workflow for Benchmark QA.

    * A Custom Agent is used to route tasks depending on whether they originates in the Benchmark Dataset or the Production Dataset.
    * A script is will be added to the Consensus block of the Production Workflow to evaluate annotator performance.

      <div>
        <img />
      </div>
  </Step>

  <Step title="Create The Production Project">
    <Warning>
      Ensure that you:

      * Attach both the Benchmark Dataset AND the Production Dataset when creating the Production Project.
      * Attach the SAME Ontology you created for the Benchmark Project.
      * Attach the Production Workflow Template to the Project.
    </Warning>

    1. In the Encord platform, navigate to **Projects**.
    2. Click the **+ New annotation project** button to create a new Project.
    3. Give the Project a meaningful title and description, for example "Benchmark QA Production Labels".
    4. Click the **Attach ontology** button and attach the Ontology you created. Attach the SAME Ontology you created for the Benchmark Project.
    5. Click the **Attach dataset** button and attach the Benchmark AND the Production Datasets.
    6. Click the **Load from template** button to attach the "Benchmark QA Production Labels" template you created in **STEP 4.2**.
    7. Click **Create Project** to create the Project.
       You have now created the Project to label production data and evaluate annotators against the benchmark labels.

    <div>
      <img />
    </div>
  </Step>

  <Step title="Create and run the SDK script for the Agent node">
    Create and run the following `benchmark_routing.py` script to check whether a data unit is part of the Benchmark Dataset, or the Production Dataset.

    * If a task is part of the Benchmark Dataset, the task is routed along the "Yes" pathway and proceeds to the Consensus 1 stage of the Production Project, where annotator performance is evaluated.
    * If the task is not part of the Benchmark Dataset it is routed along the "No" pathway and proceeds to the Annotate 1 stage of the Production Project, where production data is labeled.

    <Tip>Run this script each time new production data is added to the Production Dataset</Tip>

    ```python benchmark_routing.py theme={"dark"}
    # Import dependencies
    from encord.user_client import EncordUserClient
    from encord.workflow import AgentStage

    #Replace <project_hash> with the hash of your Project
    PROJECT_HASH = "<project_hash>"

    BENCHMARK_DATASET_HASH = "<benchmark_dataset_hash>"

    #Replace <private_key_path> with the full path to your private key
    SSH_PATH = "<private_key_path>"

    # Authenticate using the path to your private key
    user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
    )

    # Specify the Project that contains the agent.
    project = user_client.get_project(PROJECT_HASH)

    # Specify the Agent
    agent_stage = project.workflow.get_stage(name="Benchmark Task?", type_=AgentStage)
    benchmark_dataset = user_client.get_dataset(BENCHMARK_DATASET_HASH)
    benchmark_data_hashes = {data_row.uid for data_row in benchmark_dataset}

    for task in agent_stage.get_tasks():
        if task.data_hash in benchmark_data_hashes:
            task.proceed(pathway_name="YES")
        else: 
            task.proceed(pathway_name="NO")
    ```
  </Step>

  <Step title="Create a script for the Review & Refine stage">
    Crete the following `sample_evaluation.py` script for the Consensus 1 stage in the Production Project. The script compares the annotator's labels in the Production Project with the ground truth labels established in the Benchmark Project.

    <Note>
      All tasks in this stage are rejected and routed to the Archive stage, as they do not constitute production data. The point of the Consensus block is to evaluate annotator performance.
    </Note>

    ```python sample_evaluation.py theme={"dark"}
    from encord import EncordUserClient, Project

    from encord.workflow import (
        ConsensusReviewStage,
    )


    user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path="<private_key_path>"
    )

    training_project_id = "<production_project_hash>"
    production_project = user_client.get_project(training_project_id)

    groundtruth_project_id = "<groundtruth_project_hash>"
    groundtruth_project = user_client.get_project(groundtruth_project_id)


    review_stage = production_project.workflow.get_stage(name="Consensus 1 Review", type_=ConsensusReviewStage)
    task_data_hashes = [t.data_hash for t in review_stage.get_tasks()]

    # download all submitted labels and ground-truth labels
    label_rows_to_evaluate = production_project.list_label_rows_v2(
        data_hashes=task_data_hashes, 
        include_all_label_branches=True,
    )
    with production_project.create_bundle() as bundle:
        for lr in label_rows_to_evaluate:
            lr.initialise_labels(bundle=bundle)

    groundtruth_label_rows = groundtruth_project.list_label_rows_v2(data_hashes=task_data_hashes)
    with groundtruth_project.create_bundle() as bundle:
        for lr in groundtruth_label_rows:
            lr.initialise_labels(bundle=bundle)


    # for each ground-truth label row from the ground-truth project
    # 1. grab the corresponding task to be benchmarked
    # 2. evaluate the submitted labels against the ground truth, specifying the annotator being evaluated

    for gtlr in groundtruth_label_rows:
        # get all label row submissions against the ground truth task
        benchmark_label_rows = [bmlr for bmlr in label_rows_to_evaluate if bmlr.data_hash == gtlr.data_hash]
        target_task = next(review_stage.get_tasks(data_hash=gtlr.data_hash), None)

        if target_task is None:
            print("Could not find corresponding benchmark task in production project")
            continue

        # for each label row to be benchmarked, run the evaluation passing in annotator
        for bmlr in benchmark_label_rows:
            # skip the 'main' branch, it does not yet have any annotator submissions.
            if bmlr.branch_name == "main":
                continue

            annotator = next(task_option.annotator for task_option in target_task.options if task_option.branch_name == bmlr.branch_name)
            print(f"Evaluate task. Data UUID: {gtlr.data_hash}, Label Branch: {bmlr.branch_name}, Annotator: {annotator}")
            # my_eval_function(gtlr, bmlr, gtlr) <- fill in your logic here!

    ```
  </Step>
</Steps>

## STEP 5: Create labels

Once your Production Project is set up, annotators can begin labeling the production data. Tasks from both the Benchmark Dataset and the Production Dataset are assigned to annotators. Their performance is then assessed based on how accurately they label the Benchmark tasks.

<Tip>To learn how to create annotations, see our [documentation here](/platform-documentation/GettingStarted/gettingstarted-labeling).</Tip>

## STEP 6: Evaluate Annotator Performance

Run the `sample_evaluation.py` script created in **STEP 4.5** to evaluate annotator performance.


# Human-in-the-Loop Validation
Source: https://docs.encord.com/end-to-end/Features/e2e-data-groups



<span>
  Human-in-the-loop
</span>

<span>
  Multimodal
</span>

<span>
  Basic Cloud Storage
</span>

<span>
  Data Groups (text and videos)
</span>

## Why do this?

You want to guarantee correctness, completeness, or fairness in the predictions of your models.

**Quick way to get going with Data Groups in Encord using cloud data.**

<Tip>If you intend to use Encord at scale, with Data Groups, we strongly recommend using the Encord SDK.</Tip>

### Pros and Cons

<table>
  <thead>
    <tr>
      <th>Pros</th>
      <th>Cons</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        * Simple way to get data into Encord
        * Able to sync your cloud data with Encord easily
        * Data groups available for multi-tile multi-modal functionality
      </td>

      <td>
        * Requires a little bit of technical knowledge to set integrations
        * No data management or curation (custom metadata needs to be imported separately)
      </td>
    </tr>
  </tbody>
</table>

<Note>
  Data Groups can include custom metadata, but for the purposes of this end-to-end example none are included.
</Note>

## Import/Register Data

We're going to register our dataset of videos (portion of Nexar open source dataset) and text files (Events captured for the videos).

<Steps>
  <Step title="Create Integration">
    Select your cloud provider.
  </Step>

  <Step title="Download Data">
    Download and extract the contents of [nexar-first-100-osds.zip file](https://storage.googleapis.com/docs-media.encord.com/E2E%20Artifacts/nexar-first-100-osds.zip).
  </Step>

  <Step title="Re-encode Videos">
    <Tip>We strongly recommend re-encoding any videos with issues. Re-encoding your videos ensures the best performance when annotating your data.</Tip>

    You can do this locally or in your cloud storage.

    <Note>
      For more information on re-encoding videos, go [here](/platform-documentation/Curate/files/files-re-encoding).
    </Note>
  </Step>

  <Step title="Import Data to Cloud Storage">
    Import the contents of `nexar-first-100-osds.zip` into your cloud storage.
  </Step>

  <Step title="Create Cloud-synced Folder">
    Syncing the data registers the data in Encord. Your data stays in your cloud storage.

    <iframe title="Loom Video" />

    1. Navigate to **Data** > **Files & Folders**.

    2. Click **New folder > Cloud-synced folder**.
       The New Cloud-synced folder dialog appears.

    3. Provide the following:

       * **Title:** `E2E - Data Groups - Cloud-synced Folder`.
       * **Description:** OPTIONAL - Provide a meaningful description for the Cloud-synced folder.
       * **Select your integration:** Select the integration to use from the drop down.
       * **Storage path:** Specify the storage/file path to your cloud storage. For example: `gs://encord-gcp-bucket/CloudSync/` or `s3://encord-aws-bucket/CloudSync`.

    4. Click **Test** to verify that Encord can communicate with your cloud storage.

    5. Click **Create**.
       The page for the new Cloud-synced folder appears.

    #### Find Storage Path

    Finding the Storage path for your folder or object varies across Cloud Storage platforms.

    **AWS**

    ![Find AWS storage path](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/aws-storage-path.gif)

    **GCP**

    ![Find GCP storage path](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/gcp-storage-path.gif)
  </Step>

  <Step title="Sync Data Between Encord and Cloud Storage">
    1. Go to **Data** > **Files & Folders**.

    2. Click into your cloud-synced folder.

    3. Click **Initiate sync**.
       The sync between the folder and your cloud storage begins.

    <Important>
      Record the `Dataset ID` for use later.
    </Important>
  </Step>
</Steps>

## Create Ontology

Create the following Ontology for the Project.

Ontology name: `E2E - Ontology - Data Groups`

**Classifications**

* `Prediction correct?`
  * `YES!` (Radio button)
  * `No`  (Radio button)
    * `What's wrong?` (Text)

* `Summary correct?`
  * `YES!` (Radio button)
  * `No`  (Radio button)
    * `What's wrong?` (Text)

![Data Groups Ontology](https://storage.googleapis.com/docs-media.encord.com/E2E%20Artifacts/Screenshots/e2e-data-groups-ontology.png)

<iframe title="Loom Video" />

## Create Dataset

Create a Dataset for your Data Groups.

Name: `E2E - Dataset - Data Groups`

<Important>
  Record the `Dataset ID` for use later.
</Important>

<iframe title="Loom Video" />

## Create Project

Once all the videos are re-encoded, and you created an Ontology and Dataset you are ready to create an Annotate Project. Once you create a Project you need to create your Data Groups and then your team will be ready to annotate your data.

Name: `E2E - Project - Data Groups`

<Important>
  Record the `Project ID` for use later.
</Important>

<iframe title="Loom Video" />

## Mapping File for Data Units

Creating Data Groups requires mapping your data units to the layout, used during annotation and review. Currently mapping to the layout uses the File ID/UUID of the data unit Encord assigns the data unit.

To find the File ID/UUID of your data units use `storage_folder.list_items`. The following script provides a way to get the file name and ID of your data units. The output saves to a JSON and CSV file.

```python List File Name and File ID theme={"dark"}

from encord import EncordUserClient
import json
import csv

# --- 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

# Output file paths
JSON_OUTPUT_PATH = "/file/path/to/save/file_mapping.json" # Update this as required
CSV_OUTPUT_PATH = "/file/path/to/save/file_mapping.csv" # Update this as required

# Authenticate with Encord using the path to your private 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",
)

# Find the storage folder by name
folder_name = FOLDER_ID
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List all data units
    items = list(storage_folder.list_items())

    # Create a list of dicts for structured output
    file_data = [
        {
            "file_id": str(item.uuid),  # Convert UUID to string
            "file_name": item.name,
            "file_type": item.item_type
        }
        for item in items
    ]

    # --- Save to JSON File ---
    with open(JSON_OUTPUT_PATH, "w") as f:
        json.dump(file_data, f, indent=4)

    # --- Save to CSV File ---
    with open(CSV_OUTPUT_PATH, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=["file_id", "file_name", "file_type"])
        writer.writeheader()
        writer.writerows(file_data)

    print(f"Saved output to:\n- {JSON_OUTPUT_PATH}\n- {CSV_OUTPUT_PATH}")

else:
    print("Folder not found.")

```

## Create Data Groups

<Note>
  Use the output file from the `Map Data Units for Data Groups` section to map File IDs to their corresponding layout for Data Groups.
</Note>

<Tip>
  When configuring Dynamic Data Groups, you can mark individual tiles as read-only in the tile member editor. Enabling the **Read-only** toggle on a tile prevents annotators from adding labels to that tile. This is useful for reference or context tiles such as a text summary or a reference camera feed. The **Read-only** toggle appears in the tile member editor only when a layout type is configured for the group. For full details, see the [Dynamic Data Groups documentation](/platform-documentation/Curate/data-groups/index-data-groups).
</Tip>

Use the script in this section to create Data Groups, add those Data Groups to a Dataset, and add the Dataset to a Project.

The script creates Data Groups with five data units in the following layout:

```pgsql theme={"dark"}
+-------------------------------------------+
|              text file                    |
+------------------+------------------------+
|     video 1      |        video 2         |
+------------------+------------------------+
|     video 3      |        video 4         |
+------------------+------------------------+
```

To create Data Groups the File Ids for data units need to be mapped to the Data Group.

Refer to the following:

```python theme={"dark"}

# --- Group definitions (name + UUIDs) ---
groups = [
    {
        "name": "group-001",
        "uuids": {
            "instructions": UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID of clustered_event_log_01.txt
            "top-left": UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID of 00001_normalized.mp4
            "top-right": UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID of 00002_normalized.mp4
            "bottom-left": UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID of 00009.mp4
            "bottom-right": UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID of 00011_normalized.mp4
        },
    },
    {
        "name": "group-002",
        "uuids": {
            "instructions": UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID of clustered_event_log_02.txt
            "top-left": UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID of 00012.mp4
            "top-right": UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID of 00020.mp4
            "bottom-left": UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID of 00030.mp4
            "bottom-right": UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID of 00033.mp4
        },
    },
    {
        "name": "group-003",
        "uuids": {
            "instructions": UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID of clustered_event_log_03.txt
            "top-left": UUID("23232323-2323-2323-2323-232323232323"), # Replace with File ID of 00034.mp4
            "top-right": UUID("31313131-3131-3131-3131-313131313131"), # Replace with File ID of 00035_normalized.mp4
            "bottom-left": UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID of 00038_normalized.mp4
            "bottom-right": UUID("56565656-6565-5656-6565-656565656565 "), # Replace with File ID of 00045.mp4
        },
    },
    # More groups...
]
```

**Run this script to create Data Groups:**

```python theme={"dark"}

from uuid import UUID

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupCustom, StorageItemType
from encord.user_client import EncordUserClient

# --- 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)

# --- Reusable layout and settings ---
layout = {
    "direction": "column",
    "first": {"type": "data_unit", "key": "instructions"},
    "second": {
        "direction": "column",
        "first": {
            "direction": "row",
            "first": {"type": "data_unit", "key": "top-left"},
            "second": {"type": "data_unit", "key": "top-right"},
            "splitPercentage": 50,
        },
        "second": {
            "direction": "row",
            "first": {"type": "data_unit", "key": "bottom-left"},
            "second": {"type": "data_unit", "key": "bottom-right"},
            "splitPercentage": 50,
        },
        "splitPercentage": 50,
    },
    "splitPercentage": 20,
}
settings = {"tile_settings": {"instructions": {"is_read_only": True}}}

# --- Group definitions (name + UUIDs) ---
groups = [
    {
        "name": "group-001",
        "uuids": {
            "instructions": UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID of clustered_event_log_01.txt
            "top-left": UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID of 00001_normalized.mp4
            "top-right": UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID of 00002_normalized.mp4
            "bottom-left": UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID of 00009.mp4
            "bottom-right": UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID of 00011_normalized.mp4
        },
    },
    {
        "name": "group-002",
        "uuids": {
            "instructions": UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID of clustered_event_log_02.txt
            "top-left": UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID of 00012.mp4
            "top-right": UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID of 00020.mp4
            "bottom-left": UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID of 00030.mp4
            "bottom-right": UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID of 00033.mp4
        },
    },
    {
        "name": "group-003",
        "uuids": {
            "instructions": UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID of clustered_event_log_03.txt
            "top-left": UUID("23232323-2323-2323-2323-232323232323"), # Replace with File ID of 00034.mp4
            "top-right": UUID("31313131-3131-3131-3131-313131313131"), # Replace with File ID of 00035_normalized.mp4
            "bottom-left": UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID of 00038_normalized.mp4
            "bottom-right": UUID("56565656-6565-5656-6565-656565656565 "), # Replace with File ID of 00045.mp4
        },
    },
    # More groups...
]

# Create the data groups

for g in groups:
    group = folder.create_data_group(
        DataGroupCustom(
            name=g["name"],
            layout=layout,
            layout_contents=g["uuids"],
            settings=settings,
        )
    )
    print(f"✅ Created group '{g['name']}' with UUID {group}")

# Add all the data groups in a folder to a Dataset
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# Add the Dataset with the Data Groups to a Project

p = user_client.get_project(PROJECT_ID)
rows = p.list_label_rows_v2()

# Data Group labels are accessed through the parent row's Label Spaces
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        for space in row.get_spaces():
            print(
                f"space_id: {space.space_id}, "
                f"file_name: {space.metadata.file_name}, "
                f"layout_key: {space.metadata.layout_key}"
            )
```

## Annotate Data Groups

Annotation of videos depends on your Ontology. Our Ontology `E2E Data Groups` uses classifications.

In this section, you'll see the following Collaborators:

* **Annotators** labeling data
* **Reviewers** reviewing labels created by Annotators
* **Team Manager** managing the Annotators and Reviewers
* **Project Admin** managing the Project and exporting labels

<Steps>
  <Step title="Prepare to Label">
    <AccordionGroup>
      <Accordion title="Team Manager or Project Admin">
        The Team Manager or Project Admin can prioritize certain data to be labeled and reviewed first. Let's prioritize a few Data Groups to be labeled first by setting the priority for those files to `75`.

        **Set Priority to `75`**

        <iframe title="Loom Video" />
      </Accordion>

      <Accordion title="Annotators">
        Annotators can configure the Annotate Label Editor so they can more effectively and efficiently label data.

        <iframe title="Loom Video" />
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Label Data">
    <AccordionGroup>
      <Accordion title="Team Manager or Project Admin">
        The Team Manager or Project Admin can monitor the performance and progress of the annotation team.

        <iframe title="Loom Video" />
      </Accordion>

      <Accordion title="Annotators">
        Annotators use the text file to determine if the `Prediction` and `Summary` for each video are correct.

        <Note>Use hotkeys to speed up your annotation process.</Note>

        <Tip>You can [synchronize playback across all videos](/platform-documentation/Annotate/annotate-label-editor/multimodal-groups).</Tip>

        <iframe title="Loom Video" />
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Review Labels">
    <AccordionGroup>
      <Accordion title="Team Manager or Project Admin">
        The Team Manager or Project Admin can monitor the performance and progress of the review team.

        <iframe title="Loom Video" />
      </Accordion>

      <Accordion title="Review Labels">
        Reviewers verify that the labels are correct.

        <Note>You can approve labels/classifications on a task one at a time (from the left panel) or all at once (using the **Approval all** button).</Note>

        <Tip>
          When there is an issue with labels/classifications, Reviewers can:

          * Reject the task and add a comment about why a task was rejected. Rejected tasks go back to the person who added the labels/classifications.
          * Edit labels directly using the **Edit labels** button and then approve the task.
        </Tip>

        <iframe title="Loom Video" />
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Export Labels">
    Only Project Admins can export labels from Encord.

    <Accordion title="Project Admin">
      Export the labels from the Project Labels page.

      <iframe title="Loom Video" />
    </Accordion>
  </Step>
</Steps>


# Issues
Source: https://docs.encord.com/end-to-end/Features/issues-e2e



## Issues End-to-End Guide

This guide explains how to use the *Issues* feature in Encord. Each step in the process is intended for a specific user role, which is indicated in the heading of that step.

<Warning>
  This guide assumes you have already added data into Encord and set up your annotation Projects.
</Warning>

### STEP 1: \[Workspace Admin] Create Issue Tags

<Info>
  Issue tags can be created in the Workspace Settings by Workspace admins, or the Project Settings by Project admins.
</Info>

<Tip>
  For more information, refer to our [Issue Tags documentation](/platform-documentation/General/general-workspace-settings#issue-tags).
</Tip>

[Issue tags](/platform-documentation/General/general-workspace-settings#issue-tags) serve as a system to categorize, group, and filter issues within Projects.

1. Click **Settings** in the **My workspace** section.
   The Users page appears.

2. Navigate to the **Issue Tags** tab.
   The *Issue Tags* page appears.

3. Click **+ New issue tag** to create a new issue tag for your Workspace.

<div>
  <img />
</div>

4. Give your Issue Tag a meaningful name and press <kbd>ENTER</kbd> to create the Issue Tag.

5. Repeat Steps 3 and 4 to create as many Issue Tags as necessary.

#### Delete Issue Tags

You can delete issue tags individually or in bulk:

**To delete a single issue tag:**

1. Click the delete icon next to the issue tag you want to remove.
2. Confirm the deletion when prompted.

**To delete multiple issue tags:**

1. Select the checkboxes next to the issue tags you want to delete.
2. Click the **Delete selected** button that appears.
3. Confirm the bulk deletion when prompted.

<Warning>
  Deleting issue tags is permanent and cannot be undone. Ensure you no longer need these tags before proceeding.
</Warning>

### STEP 2: \[Admin] Add Issue Tags

1. Navigate to your annotation Project.

2. Navigate to the *Settings* tab.

3. Click the dropdown in the *Issue tags* section.

4. Select, or type the name of, the issue tag you want to add to the Project.

<div>
  <img />
</div>

### STEP 3: \[Annotator / Reviewer] Create Issues

<Tip>
  For more information, refer to the [Issues documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments).
</Tip>

<Note>
  Issues cannot be created in a Consensus annotate stage.
</Note>

### Tile Selection for Data Groups

For Data Groups with multiple tiles, the Issues panel includes a tile selector that allows you to:

* View issues specific to each tile
* Create issues that apply to a particular tile
* See validation warnings for missing required annotations across all tiles

The tile selector displays a badge showing the number of issues for each tile, helping you quickly identify which tiles need attention.

<AccordionGroup>
  <Accordion title="[Reviewer] Create Label Rejection Issues">
    1. Open a review task from the *Queue* tab of your annotation Project.

    2. Reject a label.
       The *Issues* pane opens.

    3. Select any [Issue Tags](/platform-documentation/General/general-workspace-settings#issue-tags) you want to apply to the issue.

    4. Add a comment explaining why the label is being rejected.

    5. Click **Reject** to create the label rejection Issue.

    <div>
      <img />
    </div>

    6. Click **Reject task** to reject the task.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="[Annotator / Reviewer] Create Other Issues">
    1. Open a task from the *Queue* tab of your annotation Project.

    2. Open the *Issues* pane by clicking the *Issues* icon.

    3. For data groups with multiple tiles, select the specific tile the issue applies to using the tile selector dropdown.

    4. Click the *New issue* icon (or keyboard shortcut <kbd>Ctrl</kbd>+<kbd>N</kbd>).

    5. Click the *Apply to* dropdown to select the type of issue you want to create.

    6. Select any [Issue Tags](/platform-documentation/General/general-workspace-settings#issue-tags) you want to apply to the issue.

    7. Add a comment to the issue.

    8. If you selected 'Pin on canvas' in Step 5, click the desired location on the canvas.

    9. Click **Create issue**.

    <div>
      <img />
    </div>
  </Accordion>
</AccordionGroup>

### Multi-Tile Validation

<Info>
  For Data Groups with multiple tiles, Encord validates that required annotations are present on each individual tile, not just at the Data Group level.
</Info>

When working with Data Groups containing multiple tiles, the Issues panel provides enhanced validation:

* **Per-tile validation**: Required classifications and attributes are checked on each tile separately
* **Visual indicators**: The Issues panel shows which tiles have missing required annotations
* **Tile-specific issues**: Missing annotation issues are created for the specific tile where they're absent

This ensures comprehensive annotation coverage across all tiles in a data group, maintaining annotation quality and completeness.

## STEP 4: \[Annotator / Reviewer] Resolve Issues

<Tip>
  More information can be found in the [Issues documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments).
</Tip>

### Filter Issues

You can filter issues in the Issues pane to focus on specific types or categories:

1. Open the *Issues* pane by clicking the *Issues* icon.

2. Click the **Filter** button to access filtering options.

3. Use the available filters:
   * **Resolution status**: Filter by resolved, unresolved, or all issues
   * **Issue types**: Filter by specific issue types (data unit, frame, annotation, etc.)
   * **Including issue tags**: Show only issues that carry the selected tags. Selecting one or more tags here limits the list to issues with those tags.
   * **Excluding issue tags**: Hide issues that carry the selected tags. Selecting one or more tags here removes matching issues from the list.
   * **Object class**: Filter by specific object or classification classes from your Ontology
   * **Comment keyword**: Search for specific text within issue comments

4. Select your desired filter criteria. The issues list updates automatically to show only matching issues.

<Note>
  The **Including issue tags** and **Excluding issue tags** filters only appear when your Project has issue tags configured. Both filters compose: an issue must match the include condition and not match any exclude condition to appear in the list. A tag selected in one section is automatically removed from the options in the other section, so the same tag cannot be both included and excluded simultaneously. Clearing all filters resets both tag filter sections.
</Note>

5. To clear all filters, click **Clear filters** or use the **Clear filters** button that appears when no issues match your current filter.

<Note>
  The object class filter shows all object and classification classes from your Project's Ontology. If no issues match your current filter, you'll see a message with an option to clear all filters.
</Note>

### Resolve Issues

1. Open a task from the *Queue* tab of your annotation Project. Rejected tasks
   The Label Editor with the *Issues* pane already opened appears.

2. Address the problem raised by the Issue.

3. Add a reply to the Issue acknowledging the issue has been addressed.

4. Resolve the Issue by clicking the *tick* icon on the thread.

<div>
  <img />
</div>

### STEP 5: \[Project Admin / Team Manager] Issue Analytics

<Note>
  The number of issue actions taken by each Project collaborator can be viewed in the **Collaborators** tab.
</Note>

1. Navigate to the **Analytics** tab of your Project.

2. Navigate to the *Issues* section.
   Analytics pertaining to Issues appear.

<div>
  <img />
</div>

The **Issue actions** chart shows the following:

* **Total issues created**: The total number of issues created.
* **Total issues resolved**: The number of issues marked as resolved.
* **Total issues reopened**: The number of issues that were reopened.

**Example - How to Understand Issue Analytics**:

If your **Issue actions** chart shows:

* Total issues created = 19
* Total issues resolved = 20
* Total issues reopened = 2

This means that:

* 19 issues were created.
* All 19 issues were resolved.
* 2 resolved issues were reopened. (This includes manually reopening an issue and re-rejections of labels)
* 1 of the reopened issues was resolved.
* There is one remaining open issue.

## Creating Issues With Agents

Issues can be created inside an [Agent Workflow Stage](/sdk-documentation/projects-sdk/sdk-workflows-stages#workflow-basics). The following example shows how to list all issues, and create file-level, frame-level, and coordinate-level issues on tasks within an Agent stage.

```python theme={"dark"}
from encord import EncordUserClient
from encord.workflow import AgentStage

# User input
SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
PROJECT_ID = "<project_id>"      # Replace with the unique Project ID
AGENT_STAGE_NAME = "<agent_stage_name>"  # Replace with the name of your Agent stage

# --- Connect to Encord ---
user_client = 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 and Workflow
project = user_client.get_project(PROJECT_ID)
workflow = project.workflow

# Get the Agent stage and iterate over its tasks
agent_stage = workflow.get_stage(name=AGENT_STAGE_NAME, type_=AgentStage)
for task in agent_stage.get_tasks():

    # List all existing issues on the task
    existing_issues = list(task.issues.list())
    print(f"Task {task.uuid} has {len(existing_issues)} existing issue(s)")

    # Add a file-level issue (applies to the entire data unit)
    task.issues.add_file_issue(
        description="File is corrupted or unreadable",
    )

    # Add a frame-level issue (applies to a specific frame)
    task.issues.add_frame_issue(
        frame=0,
        description="Motion blur makes annotation impossible on this frame",
    )

    # Add a coordinate-level issue (applies to a specific location within a frame)
    task.issues.add_coordinate_issue(
        frame=0,
        x=0.5,
        y=0.5,
        description="Ambiguous object boundary at this location",
    )

    print(f"Issues added to task {task.uuid}")
```


# Data Annotation
Source: https://docs.encord.com/end-to-end/GettingStartedE2E/data-annotation



## STEP 1: Register Your Files With Encord

### Create a Cloud Integration

Select your cloud provider.

<div lang="en">
  <head>
    <meta />

    <meta name="viewport" />

    <title>Clickable Div</title>
  </head>

  <div>
    <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration">
      AWS Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration">
      GCP Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration">
      Azure Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-otc-integration">
      OTC Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-wasabi-integration">
      Wasabi Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-oracle-integration">
      Oracle Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-direct-access-integration">
      Direct Access Integration
    </a>
  </div>
</div>

***

### Create a Folder

You must create a folder in Index to store your files.

1. Navigate to **Data** > **Files & Folders**
2. Click the **+ New folder** button to create a new folder. Select the type of folder you want to create.

<div>
  <img />
</div>

3. Give the folder a meaningful name and description.

4. Click **Create** to create the folder.
   The folder is listed in **Files & Folders**.

***

### Create JSON or CSV for Registration

To import files from cloud storage into Encord, you must create a JSON or CSV file specifying the files you want to register.

<Tip>
  Find helpful scripts for creating JSON and CSV files for the data registration process [here](/platform-documentation/Curate/add-files/index-register-cloud-data#helpful-scripts-and-examples).
</Tip>

All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

<Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data)</Note>

<Info>Encord supports file names up to 300 characters in length for any file or video for upload.</Info>

<Info>
  Encord enforces the following upload limits for each JSON file used for file registration:

  * Up to 1 million URLs
  * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  * URLs can be up to 16 KB in size

  Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
</Info>

<Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

<AccordionGroup>
  <Accordion title="JSON Format">
    #### Create JSON file for Registration

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

    <Note>If `skip_duplicate_urls` is set to `true`, all object URLs that exactly match existing images/videos in the dataset are skipped.</Note>

    <Accordion title="JSON for AWS">
      #### AWS JSON

      <AccordionGroup>
        <Accordion title="Videos">
          #### [Videos](#videos)

          **Video Metadata**

          When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

          <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "cloud-path-to-your-video-1"
                },
                {
                  "objectUrl": "cloud-path-to-your-video-2",
                    "videoMetadata": {
                      "fps": frames-per-second,
                      "duration": duration-in-seconds,
                      "width": frame-width,
                      "height": frame-height,
                      "file_size": file-size-in-bytes,
                      "mime_type": "MIME-file-type-extension"
                    }
                  }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/BerghouseLeopardJog.mp4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blue_bus_video.mp4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/bluemlisalphutte_flyover.mp4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake_normalized.mp4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/snow_sled.MOV"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cyclists.MP4"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Video Metadata theme={"dark"}
            {
                "videos": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/video_file.mp4",
                    "videoMetadata": {
                        "fps": 23.98,
                        "duration": 29.09,
                        "width": 1280,
                        "height": 720,
                        "file_size": 5468354,
                        "mime_type": "video/mp4"
                    }
                  }
                ],
              "skip_duplicate_urls": true
              }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Audio files">
          #### [Audio Files](#audio-files)

          The following is an example JSON file for uploading two audio files to Encord.

          <Tip>
            Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
          </Tip>

          * **Template:** Imports audio files with an Encord title.
          * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "audio": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-custom-audio-file-title.mp3"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Audio Metadata theme={"dark"}
            {
                "audio": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file.mp3",
                    "audioMetadata": {
                        "duration": 23.98,
                        "file_size": 2900000,
                        "mime_type": "audio/mp3",
                        "sample_rate": 44100,
                        "bit_depth": 24,
                        "codec": "mp3",
                        "num_channels": 2
                    }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="PDFs">
          #### [PDFs](#pdfs)

          The following are example JSON files for uploading PDFs to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "pdfs": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-document-02.pdf"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-document-03.pdf",
                  "pdfMetadata": {
                    "fileSize": 300,
                    "numPages": 5
                    }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "pdfs": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-01.pdf",

                  },
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-02.pdf",
                    "title": "my-document-02.pdf"
                  },
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-03.pdf",
                    "title": "my-document-03.pdf",
                    "pdfMetadata": {
                      "fileSize": 300,
                      "numPages": 5
                      }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Text Files">
          #### [Text Files](#text-files)

          The following are example JSON files for uploading text files to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "text": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-file.html"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-plain-text-file.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "<object url_4>",
                  "title": "my-csv-file.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "<object url_5>",
                  "title": "my-xml-file.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "<object url_6>",
                  "title": "my-html-file.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "text": [
                  {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-file-01.html"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-01.txt",
                  "title": "my-plain-text-file-01.txt"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-02.txt",
                  "title": "my-plain-text-file-02.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-csv-file-01.csv",
                  "title": "my-csv-file-01.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-xml-file-01.xml",
                  "title": "my-xml-file-01.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-html-file-01.html",
                  "title": "my-html-file-01.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Single images">
          #### [Single Images](#single-images)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          The JSON structure for single images parallels that of videos.

          **Template:** Provides the proper JSON format to import images into Encord.

          **Examples:**

          * **Data** Imports the images only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "file/path/to/images/file-name-01.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-02.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-03.file-extension",
                  "title": "image-title.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data    theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.jpg"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0003.jpg"
                },
                {
                  "objectUrl": "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"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/large_images/pexels-ivo-rainha-00057.png"
                }
              ]
            }
            ```

            ```json Image Metadata theme={"dark"}

            {
              "images": [
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/my_image.jpg",
                  "imageMetadata": {
                    "mimeType": "image/jpg",
                    "fileSize": 124,
                    "width": 640,
                    "height": 480
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image groups">
          #### [Image groups](#image-groups)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image groups are collections of images that are processed as one annotation task.
          * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
          * Image groups do NOT require 'write' permissions to your cloud storage.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the image groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "image_groups": [
                {
                  "title": "<title 1>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                },
                {
                  "title": "<title 2>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image group 01",
                  "createVideo": false,
                  "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg",
                  "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.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 group 02",
                  "createVideo": false,
                  "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0001.jpg",
                  "objectUrl_1": "<https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0002.jpg",
                  "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0003.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image sequences">
          #### [Image sequences](#image-sequences)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image sequences are collections of images that are processed as one annotation task and represented as a video.
          * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
          * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
          * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

          <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the images groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "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>"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "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
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="DICOM">
          #### [DICOM](#dicom)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Each `dicom_series` element can contain one or more DICOM series.
          * Each series requires a title and at least one object URL, as shown in the example below.
          * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

          <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

          The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

          * The first series contains only a single object URL, as it is composed of a single file.
          * The second series contains 3 object URLs, as it is composed of three separate files.
          * The third series contains 2 object URLs, as it is composed of two separate files.

          <Info>
            For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
          </Info>

          ```json Template theme={"dark"}
          {
            "dicom_series": [
              {
                "title": "Series-1",
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series1-file.dcm"
              },
              {
                "title": "Series-2",
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file1.dcm",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file2.dcm",
                "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file3.dcm",
              },
                {
                "title": "Series-3",
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file1.dcm",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file2.dcm",
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="NIfTI">
          #### [NIfTI](#nifti)

          The following is an example JSON file for uploading two NIfTI files to Encord.

          ```json Template theme={"dark"}
          {
              "nifti": [
                {
                  "title": "<file-1>",
                  "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                },
                {
                  "title": "<file-2>",
                  "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                }
              ],
              "skip_duplicate_urls": true
            }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title=" Multiple file types ">
          You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

          ```json Multiple file types theme={"dark"}

          {
            "images": [
              {
                "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/Image1.png"
              }
            ],
            "videos": [
              {
                "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Cooking.mp4"
              },
              {
                "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Oranges.mp4"
              }
            ],
            "image_groups": [
              {
                "title": "apple-samsung-light",
                "createVideo": true,
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(32).jpg",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
                "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
                "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
              },
              {
                "title": "apple-samsung-dark",
                "createVideo": true,
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(32).jpg",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(33).jpg",
                "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(34).jpg",
                "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(35).jpg"
              }
            ],
            "image_groups": [
              {
                "title": "apple-ios-light",
                "createVideo": false,
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(32).jpg",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(33).jpg"
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    <Accordion title="JSON for GCP">
      #### GCP JSON

      <AccordionGroup>
        <Accordion title="Videos">
          #### [Videos](#videos)

          **Video Metadata**

          When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

          <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "cloud-path-to-your-video-1"
                },
                {
                  "objectUrl": "cloud-path-to-your-video-2",
                    "videoMetadata": {
                      "fps": frames-per-second,
                      "duration": duration-in-seconds,
                      "width": frame-width,
                      "height": frame-height,
                      "file_size": file-size-in-bytes,
                      "mime_type": "MIME-file-type-extension"
                    }
                  }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/eLeopardJog.mp4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/_video.mp4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/bluemlisalphutte_flyover.mp4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake_normalized.mp4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/snow_sled.MOV"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/cyclists.MP4"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Video Metadata theme={"dark"}
            {
                "videos": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/video_file.mp4",
                    "videoMetadata": {
                        "fps": 23.98,
                        "duration": 29.09,
                        "width": 1280,
                        "height": 720,
                        "file_size": 5468354,
                        "mime_type": "video/mp4"
                    }
                  }
                ],
                "skip_duplicate_urls": true
              }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Audio files">
          #### [Audio Files](#audio-files)

          The following is an example JSON file for uploading two audio files to Encord.

          <Tip>
            Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
          </Tip>

          * Example 1 imports audio files with an Encord title.
          * Example 2 imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "audio": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-custom-audio-file-title.mp3"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Audio Metadata theme={"dark"}
            {
                "audio": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/audio_file.mp3",
                    "audioMetadata": {
                        "duration": 23.98,
                        "file_size": 2900000,
                        "mime_type": "audio/mp3",
                        "sample_rate": 44100,
                        "bit_depth": 24,
                        "codec": "mp3",
                        "num_channels": 2
                    }
                  }
                ],
                "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="PDFs">
          #### [PDFs](#pdfs)

          The following are example JSON files for uploading PDFs to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "pdfs": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-document-02.pdf"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-document-03.pdf",
                  "pdfMetadata": {
                    "fileSize": 300,
                    "numPages": 5
                    }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "pdfs": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-01.pdf",

                  },
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-02.pdf",
                    "title": "my-document-02.pdf"
                  },
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-03.pdf",
                    "title": "my-document-03.pdf",
                    "pdfMetadata": {
                      "fileSize": 300,
                      "numPages": 5
                      }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Text Files">
          #### [Text Files](#text-files)

          The following are example JSON files for uploading text files to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "text": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-file.html"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-plain-text-file.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "<object url_4>",
                  "title": "my-csv-file.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "<object url_5>",
                  "title": "my-xml-file.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "<object url_6>",
                  "title": "my-html-file.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "text": [
                  {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-file-01.html"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-01.txt",
                  "title": "my-plain-text-file-01.txt"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-02.txt",
                  "title": "my-plain-text-file-02.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-csv-file-01.csv",
                  "title": "my-csv-file-01.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-xml-file-01.xml",
                  "title": "my-xml-file-01.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-html-file-01.html",
                  "title": "my-html-file-01.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Single images">
          #### [Single Images](#single-images)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          The JSON structure for single images parallels that of videos.

          **Template:** Provides the proper JSON format to import images into Encord.

          **Examples:**

          * **Data** Imports the images only.

          * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "file/path/to/images/file-name-01.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-02.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-03.file-extension",
                  "title": "image-title.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/0001.jpg"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0003.jpg"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/large_images/pexels-ivo-rainha-00057.png"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Image Metadata theme={"dark"}

            {
              "images": [
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/my_image.jpg",
                  "imageMetadata": {
                    "mimeType": "image/jpg",
                    "fileSize": 124,
                    "width": 640,
                    "height": 480
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image groups">
          #### [Image groups](#image-groups)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image groups are collections of images that are processed as one annotation task.
          * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
          * Image groups do NOT require 'write' permissions to your cloud storage.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the image groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "image_groups": [
                {
                  "title": "<title 1>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                },
                {
                  "title": "<title 2>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image group 01",
                  "createVideo": false,
                  "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/0001.jpg",
                  "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg",
                  "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "title": "Image group 02",
                  "createVideo": false,
                  "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0001.jpg",
                  "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-0002.jpg",
                  "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0003.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image sequences">
          #### [Image sequences](#image-sequences)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image sequences are collections of images that are processed as one annotation task and represented as a video.
          * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
          * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
          * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

          <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the images groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "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>"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image sequence 001",
                  "createVideo": true,
                  "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/01.jpg",
                  "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/02.jpg",
                  "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/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://storage.cloud.google.com/encord-image-bucket/images/thing-01.jpg",
                  "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-02.jpg",
                  "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-03.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="DICOM">
          #### [DICOM](#dicom)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Each `dicom_series` element can contain one or more DICOM series.
          * Each series requires a title and at least one object URL, as shown in the example below.
          * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

          <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

          The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

          * The first series contains only a single object URL, as it is composed of a single file.
          * The second series contains 3 object URLs, as it is composed of three separate files.
          * The third series contains 2 object URLs, as it is composed of two separate files.

          <Info>
            For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
          </Info>

          ```json JSON for DICOM theme={"dark"}
          {
            "dicom_series": [
              {
                "title": "Series-1",
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series1-file.dcm"
              },
              {
                "title": "Series-2",
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file1.dcm",
                "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file2.dcm",
                "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file3.dcm",
              },
                {
                "title": "Series-3",
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file1.dcm",
                "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file2.dcm",
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="NIfTI">
          #### [NIfTI](#nifti)

          The following is an example JSON file for uploading two NIfTI files to Encord.

          ```json theme={"dark"}
          {
              "nifti": [
                {
                  "title": "<file-1>",
                  "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                },
                {
                  "title": "<file-2>",
                  "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                }
              ],
              "skip_duplicate_urls": true
            }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title=" Multiple file types ">
          You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

          ```json Multiple file types theme={"dark"}

          {
            "images": [
              {
                "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/Image1.png"
              }
            ],
            "videos": [
              {
                "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Cooking.mp4"
              },
              {
                "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Oranges.mp4"
              }
            ],
            "image_groups": [
              {
                "title": "apple-samsung-light",
                "createVideo": true,
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/1+(32).jpg",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
                "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
                "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
              },
              {
                "title": "apple-samsung-dark",
                "createVideo": true,
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/2+(32).jpg",
                "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/2+(33).jpg",
                "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/2+(34).jpg",
                "objectUrl_3": "https://storage.cloud.google.com/encord-image-bucket/images/2+(35).jpg"
              }
            ],
            "image_groups": [
              {
                "title": "apple-ios-light",
                "createVideo": false,
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/3+(32).jpg",
                "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/3+(33).jpg"
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    <Accordion title="JSON for Azure">
      #### Azure JSON

      <AccordionGroup>
        <Accordion title="Videos">
          #### [Videos](#videos)

          **Video Metadata**

          When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

          <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "cloud-path-to-your-video-1"
                },
                {
                  "objectUrl": "cloud-path-to-your-video-2",
                    "videoMetadata": {
                      "fps": frames-per-second,
                      "duration": duration-in-seconds,
                      "width": frame-width,
                      "height": frame-height,
                      "file_size": file-size-in-bytes,
                      "mime_type": "MIME-file-type-extension"
                    }
                  }
                {
                  "objectUrl": "cloud-path-to-your-video-3",
                  "title": "title-for-your-video-3"

                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/BerghouseLeopardJog.mp4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/blue_bus_video.mp4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/bluemlisalphutte_flyover.mp4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake_normalized.mp4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/snow_sled.MOV"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/cyclists.MP4"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Video Metadata theme={"dark"}
            {
                "videos": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/video_file.mp4",
                    "videoMetadata": {
                        "fps": 23.98,
                        "duration": 29.09,
                        "width": 1280,
                        "height": 720,
                        "file_size": 5468354,
                        "mime_type": "video/mp4"
                    }
                  }
                ],
                "skip_duplicate_urls": true
              }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Audio files">
          #### [Audio Files](#audio-files)

          The following is an example JSON file for uploading two audio files to Encord.

          <Tip>
            Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
          </Tip>

          * **Template:** Imports audio files with an Encord title.
          * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "audio": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-custom-audio-file-title.mp3"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Audio Metadata theme={"dark"}
            {
                "audio": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/audio_file.mp3",
                    "audioMetadata": {
                        "duration": 23.98,
                        "file_size": 2900000,
                        "mime_type": "audio/mp3",
                        "sample_rate": 44100,
                        "bit_depth": 24,
                        "codec": "mp3",
                        "num_channels": 2
                    }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="PDFs">
          #### [PDFs](#pdfs)

          The following are example JSON files for uploading PDFs to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "pdfs": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-document-02.pdf"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-document-03.pdf",
                  "pdfMetadata": {
                    "fileSize": 300,
                    "numPages": 5
                    }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "pdfs": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-01.pdf",

                  },
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-02.pdf",
                    "title": "my-document-02.pdf"
                  },
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-03.pdf",
                    "title": "my-document-03.pdf",
                    "pdfMetadata": {
                      "fileSize": 300,
                      "numPages": 5
                      }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Text Files">
          #### [Text Files](#text-files)

          The following are example JSON files for uploading text files to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "text": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-file.html"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-plain-text-file.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "<object url_4>",
                  "title": "my-csv-file.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "<object url_5>",
                  "title": "my-xml-file.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "<object url_6>",
                  "title": "my-html-file.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "text": [
                  {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-file-01.html"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-01.txt",
                  "title": "my-plain-text-file-01.txt"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-02.txt",
                  "title": "my-plain-text-file-02.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-csv-file-01.csv",
                  "title": "my-csv-file-01.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-xml-file-01.xml",
                  "title": "my-xml-file-01.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-html-file-01.html",
                  "title": "my-html-file-01.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Single images">
          #### [Single Images](#single-images)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          The JSON structure for single images parallels that of videos.

          **Template:** Provides the proper JSON format to import images into Encord.

          **Examples:**

          * **Data** Imports the images only.

          * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "file/path/to/images/file-name-01.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-02.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-03.file-extension",
                  "title": "image-title.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0003.jpg"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/large_images/pexels-ivo-rainha-00057.png"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Image Metadata theme={"dark"}

            {
              "images": [
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my_image.jpg",
                  "imageMetadata": {
                    "mimeType": "image/jpg",
                    "fileSize": 124,
                    "width": 640,
                    "height": 480
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image groups">
          #### [Image groups](#image-groups)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image groups are collections of images that are processed as one annotation task.
          * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
          * Image groups do NOT require 'write' permissions to your cloud storage.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the image groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "image_groups": [
                {
                  "title": "<title 1>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                },
                {
                  "title": "<title 2>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image group 01",
                  "createVideo": false,
                  "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg",
                  "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg",
                  "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "title": "Image group 02",
                  "createVideo": false,
                  "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0001.jpg",
                  "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0002.jpg",
                  "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-0003.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image sequences">
          #### [Image sequences](#image-sequences)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image sequences are collections of images that are processed as one annotation task and represented as a video.
          * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
          * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
          * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

          <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the images groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "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>"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image sequence 001",
                  "createVideo": true,
                  "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/01.jpg",
                  "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/02.jpg",
                  "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/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://myaccount.blob.core.windows.net/encordcontainer/thing-01.jpg",
                  "objectUrl_1": "<https://myaccount.blob.core.windows.net/encordcontainer/thing-02.jpg",
                  "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-03.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="DICOM">
          #### [DICOM](#dicom)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Each `dicom_series` element can contain one or more DICOM series.
          * Each series requires a title and at least one object URL, as shown in the example below.
          * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

          <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

          The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

          * The first series contains only a single object URL, as it is composed of a single file.
          * The second series contains 3 object URLs, as it is composed of three separate files.
          * The third series contains 2 object URLs, as it is composed of two separate files.

          <Info>
            For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
          </Info>

          ```json Template theme={"dark"}
          {
            "dicom_series": [
              {
                "title": "Series-1",
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series1-file.dcm"
              },
              {
                "title": "Series-2",
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file1.dcm",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file2.dcm",
                "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file3.dcm",
              },
                {
                "title": "Series-3",
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file1.dcm",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file2.dcm",
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="NIfTI">
          #### [NIfTI](#nifti)

          The following is an example JSON file for uploading two NIfTI files to Encord.

          ```json Template theme={"dark"}
          {
              "nifti": [
                {
                  "title": "<file-1>",
                  "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                },
                {
                  "title": "<file-2>",
                  "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                }
              ],
              "skip_duplicate_urls": true
            }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title=" Multiple file types ">
          You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

          ```json theme={"dark"}

          {
            "images": [
              {
                "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Image1.png"
              }
            ],
            "videos": [
              {
                "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Cooking.mp4"
              },
              {
                "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Oranges.mp4"
              }
            ],
            "image_groups": [
              {
                "title": "apple-samsung-light",
                "createVideo": true,
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(32).jpg",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(33).jpg",
                "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(34).jpg",
                "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(35).jpg"
              },
              {
                "title": "apple-samsung-dark",
                "createVideo": true,
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(32).jpg",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(33).jpg",
                "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(34).jpg",
                "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(35).jpg"
              }
            ],
            "image_groups": [
              {
                "title": "apple-ios-light",
                "createVideo": false,
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(32).jpg",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(33).jpg"
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    <Accordion title="JSON for OTC">
      #### OTC JSON

      <AccordionGroup>
        <Accordion title="Videos">
          #### [Videos](#videos)

          **Video Metadata**

          When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

          <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "cloud-path-to-your-video-1"
                },
                {
                  "objectUrl": "cloud-path-to-your-video-2",
                    "videoMetadata": {
                      "fps": frames-per-second,
                      "duration": duration-in-seconds,
                      "width": frame-width,
                      "height": frame-height,
                      "file_size": file-size-in-bytes,
                      "mime_type": "MIME-file-type-extension"
                    }
                  }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/og.mp4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/blue_bus_video.mp4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/bluemlisalphutte_flyover.mp4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake_normalized.mp4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/snow_sled.MOV"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/cyclists.MP4"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Video Metadata theme={"dark"}
            {
                "videos": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/video_file.mp4",
                    "videoMetadata": {
                        "fps": 23.98,
                        "duration": 29.09,
                        "width": 1280,
                        "height": 720,
                        "file_size": 5468354,
                        "mime_type": "video/mp4"
                    }
                  }
                ],
                "skip_duplicate_urls": true
              }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Audio files">
          #### [Audio Files](#audio-files)

          The following is an example JSON file for uploading two audio files to Encord.

          <Tip>
            Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
          </Tip>

          * **Template:**  Imports audio files with an Encord title.
          * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "audio": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-custom-audio-file-title.mp3"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Audio Metadata theme={"dark"}
            {
                "audio": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/audio/audio_file.mp3",
                    "audioMetadata": {
                        "duration": 23.98,
                        "file_size": 2900000,
                        "mime_type": "audio/mp3",
                        "sample_rate": 44100,
                        "bit_depth": 24,
                        "codec": "mp3",
                        "num_channels": 2
                    }
                  }
                ],
                "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="PDFs">
          #### [PDFs](#pdfs)

          The following are example JSON files for uploading PDFs to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "pdfs": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-document-02.pdf"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-document-03.pdf",
                  "pdfMetadata": {
                    "fileSize": 300,
                    "numPages": 5
                    }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "pdfs": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-01.pdf",

                  },
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-02.pdf",
                    "title": "my-document-02.pdf"
                  },
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-3.pdf",
                    "title": "my-document-03.pdf",
                    "pdfMetadata": {
                      "fileSize": 300,
                      "numPages": 5
                      }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Text Files">
          #### [Text Files](#text-files)

          The following are example JSON files for uploading text files to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "text": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-file.html"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-plain-text-file.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "<object url_4>",
                  "title": "my-csv-file.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "<object url_5>",
                  "title": "my-xml-file.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "<object url_6>",
                  "title": "my-html-file.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "text": [
                  {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-file-01.html"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-01.txt",
                  "title": "my-plain-text-file-01.txt"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-02.txt",
                  "title": "my-plain-text-file-02.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-csv-file-01.csv",
                  "title": "my-csv-file-01.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-xml-file-01.xml",
                  "title": "my-xml-file-01.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-html-file-01.html",
                  "title": "my-html-file-01.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Single images">
          #### [Single Images](#single-images)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          The JSON structure for single images parallels that of videos.

          **Template:** Provides the proper JSON format to import images into Encord.

          **Examples:**

          * **Data** Imports the images only.

          * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "file/path/to/images/file-name-01.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-02.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-03.file-extension",
                  "title": "image-title.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0003.jpg"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/large_images/pexels-ivo-rainha-00057.png"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Image Metadata theme={"dark"}

            {
              "images": [
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my_image.jpg",
                  "imageMetadata": {
                    "mimeType": "image/jpg",
                    "fileSize": 124,
                    "width": 640,
                    "height": 480
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image groups">
          #### [Image groups](#image-groups)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image groups are collections of images that are processed as one annotation task.
          * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
          * Image groups do NOT require 'write' permissions to your cloud storage.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the image groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "image_groups": [
                {
                  "title": "<title 1>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                },
                {
                  "title": "<title 2>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                  "clientMetadata": {"optional": "metadata"}
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image group 01",
                  "createVideo": false,
                  "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg",
                  "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg",
                  "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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 group 02",
                  "createVideo": false,
                  "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0001.jpg",
                  "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0002.jpg",
                  "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0003.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image sequences">
          #### [Image sequences](#image-sequences)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image sequences are collections of images that are processed as one annotation task and represented as a video.
          * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
          * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
          * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

          <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the images groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "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>"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image sequence 001",
                  "createVideo": true,
                  "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/01.jpg",
                  "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/02.jpg",
                  "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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-bucket.obs.eu-de.otc.t-systems.com/images/thing-01.jpg",
                  "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-02.jpg",
                  "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-03.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="DICOM">
          #### [DICOM](#dicom)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Each `dicom_series` element can contain one or more DICOM series.
          * Each series requires a title and at least one object URL, as shown in the example below.
          * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

          <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

          The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

          * The first series contains only a single object URL, as it is composed of a single file.
          * The second series contains 3 object URLs, as it is composed of three separate files.
          * The third series contains 2 object URLs, as it is composed of two separate files.

          <Info>
            For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
          </Info>

          ```json JSON for DICOM theme={"dark"}
          {
            "dicom_series": [
              {
                "title": "Series-1",
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series1-file.dcm"
              },
              {
                "title": "Series-2",
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file1.dcm",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file2.dcm",
                "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file3.dcm",
              },
                {
                "title": "Series-3",
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file1.dcm",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file2.dcm",
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="NIfTI">
          #### [NIfTI](#nifti)

          The following is an example JSON file for uploading two NIfTI files to Encord.

          ```json theme={"dark"}
          {
              "nifti": [
                {
                  "title": "<file-1>",
                  "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                },
                {
                  "title": "<file-2>",
                  "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                }
              ],
              "skip_duplicate_urls": true
            }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title=" Multiple file types ">
          You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

          ```json Multiple file types theme={"dark"}

          {
            "images": [
              {
                "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/Image1.png"
              }
            ],
            "videos": [
              {
                "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Cooking.mp4"
              },
              {
                "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Oranges.mp4"
              }
            ],
            "image_groups": [
              {
                "title": "apple-samsung-light",
                "createVideo": true,
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(32).jpg",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(33).jpg",
                "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(34).jpg",
                "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(35).jpg"
              },
              {
                "title": "apple-samsung-dark",
                "createVideo": true,
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(32).jpg",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(33).jpg",
                "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(34).jpg",
                "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(35).jpg"
              }
            ],
            "image_groups": [
              {
                "title": "apple-ios-light",
                "createVideo": false,
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(32).jpg",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(33).jpg"
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    <Accordion title="JSON for AWS Multi-Region Access Point">
      #### Use a Multi-Region Access Point

      When using a Multi-Region Access Point for your AWS S3 buckets the JSON file has to be slightly different from the examples provided. Instead of an object's URL, objects are specified using the ARN of the Multi-Region Access Point followed by the object name. The example below shows how video files from a Multi-Region Access Point would be specified.

      ```json theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
          },
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
            "title": "my-custom-video-title.mp4"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_1.mp4"
          },
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_2.mp4",
            "title": "many-cute-cats.mp4"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </Accordion>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="CSV Format">
    #### Create CSV File for Registration

    In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file.

    Details for each data format are given in the sections below.

    <Info>Encord supports up to 10,000 entries for upload in the CSV file.</Info>

    <Warning>
      * Object URLs can't contain whitespace.
      * For backwards compatibility reasons, a single column CSV is supported. A file with the single `ObjectUrl` column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: "Expected a video, got a file of type XXX".
    </Warning>

    <AccordionGroup>
      <Accordion title="Videos">
        #### Videos

        A CSV file containing videos should contain two columns with the following mandatory column headings:\
        'ObjectURL' and 'Video title'. All headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the video resource.

        * The 'Video title' column containing the `video_title`. If left blank, the original file name is used.

        In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

        | ObjectUrl                           | Video title |
        | ----------------------------------- | ----------- |
        | path/to/storage-location/frame1.mp4 | Video 1     |
        | path/to/storage-location/frame2.mp4 | Video 2     |
        | path/to/storage-location/frame3.mp4 |             |
        | path/to/storage-location/frame4.mp4 | Video 3     |
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Single images">
        A CSV file containing single images should contain two columns with the following mandatory headings:\
        'ObjectURL' and 'Image title'.  All headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the image resource.

        * The 'Image title' column containing the `image_title`. If left blank, the original file name is used.

        In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

        | ObjectUrl                           | Image title |
        | ----------------------------------- | ----------- |
        | path/to/storage-location/frame1.jpg | Image 1     |
        | path/to/storage-location/frame2.jpg | Image 2     |
        | path/to/storage-location/frame3.jpg |             |
        | path/to/storage-location/frame4.jpg | Image 3     |
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Image groups">
        #### Image groups

        A CSV file containing image groups should contain three columns with the following mandatory headings:\
        'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

        * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image group a file will be assigned to.

        In the example below the first two URLs are grouped together into 'Group 1', while the following two files are grouped together into 'Group 2'.

        | ObjectUrl                           | Image group title | Create video |
        | ----------------------------------- | ----------------- | ------------ |
        | path/to/storage-location/frame1.jpg | Group 1           | false        |
        | path/to/storage-location/frame2.jpg | Group 1           | false        |
        | path/to/storage-location/frame3.jpg | Group 2           | false        |
        | path/to/storage-location/frame4.jpg | Group 2           | false        |

        <Note>Image groups do not require 'write' permissions.</Note>
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Image sequences">
        #### Image sequences

        A CSV file containing image sequences should contain three columns with the following mandatory headings: 'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

        * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.

        * The 'Create video' column. This can be left blank, as the default value is 'true'.

        In the example below the first two URLs are grouped together into 'Sequence 1', while the second two files are grouped together into 'Sequence 2'.

        | ObjectUrl                           | Image group title | Create video |
        | ----------------------------------- | ----------------- | ------------ |
        | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
        | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
        | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
        | path/to/storage-location/frame4.jpg | Sequence 2        | true         |

        <Tip>Image groups and image sequences are only distinguished by the presence of the 'Create video' column.</Tip>

        <Note>Image sequences require 'write' permissions against your storage bucket to save the compressed video.</Note>
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="DICOM">
        A CSV file containing DICOM files should contain two columns with the following mandatory headings: 'ObjectURL' and 'Dicom title'. Both headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

        * The 'Series title' column containing the `dicom_title`. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.

        In the example below the first two files are grouped into 'dicom series 1', the next two files are grouped into 'dicom series 2', while the final file will remain separated as 'dicom series 3'.

        | ObjectUrl                           | Series title   |
        | ----------------------------------- | -------------- |
        | path/to/storage-location/frame1.dcm | dicom series 1 |
        | path/to/storage-location/frame2.dcm | dicom series 1 |
        | path/to/storage-location/frame3.dcm | dicom series 2 |
        | path/to/storage-location/frame4.dcm | dicom series 2 |
        | path/to/storage-location/frame5.dcm | dicom series 3 |
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title=" Multiple file types ">
        #### Multiple file types

        You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.

        <Warning>Since the 'Create video' column defaults to `true` all files that **are not** image sequences must contain the value `false`</Warning>

        The example below shows a CSV file for the following:

        * Two image sequences composed of 2 files each.
        * One image group composed of 2 files.
        * One single image.
        * One video.

        | ObjectUrl                           | Image group title | Create video |
        | ----------------------------------- | ----------------- | ------------ |
        | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
        | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
        | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
        | path/to/storage-location/frame4.jpg | Sequence 2        | true         |
        | path/to/storage-location/frame5.jpg | Group 1           | false        |
        | path/to/storage-location/frame6.jpg | Group 1           | false        |
        | ObjectUrl                           | Image title       | Create video |
        | path/to/storage-location/frame1.jpg | Image 1           | false        |
        | ObjectUrl                           | Image title       | Create video |
        | full/storage/path/video.mp4         | Video 1           | false        |
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

***

### Import or Register your data

<AccordionGroup>
  <Accordion title="Register Cloud Data">
    #### Register Cloud Data

    <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

    1. Navigate to **Data** > **Files & Folders** in the Encord platform.
    2. Click into a Folder.
    3. Click **+ Upload files**.
       A dialog appears.

    <div>
      <img />
    </div>

    4. Click **Import from cloud data**.

    <div>
      <img />
    </div>

    <Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

    6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Import Local Data">
    #### Import Local Data

    <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

    1. Navigate to **Data** > **Files & Folders** in the Encord platform.
    2. Click into a Folder.
    3. Click **+ Upload files**.
       A dialog appears.

    <img />

    4. Click one of the following:
       * **Upload:** Upload images, videos, and audio files.
         ![Upload dialog](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-001.png)
       * **Batch images as:** Upload image batches as image groups or image sequences.
         ![Batch images as](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-02.png)
       * **DICOM/NifTi:** Upload DICOM or NifTi series.
         ![DICOM/NifTi](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-03.png)

    5. Click **Upload** after selecting your images or series.

       Your files upload into the Folder in Encord.
  </Accordion>
</AccordionGroup>

***

## STEP 2: Set Up Your Project

### Create a Dataset

A Dataset is a subset of files that can be attached to one or more Projects for annotation.

1. Click the **New dataset** button in the *Datasets* section in *Annotate*.

<div>
  <img />
</div>

2. Give your Dataset a meaningful title and description. A clear title and description keeps your data organized.

<Tip>Toggle  **Looking to create a mirrored dataset?** to create a [Mirrored Dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets#mirrored-datasets). </Tip>

<div>
  <img />
</div>

3. Click **Create dataset** to create the Dataset.

### Attach files

<Tip>[You can add data to Datasets from the **Files & Folders** or the *Datasets* screens](/platform-documentation/Curate/index-files#add-data-to-datasets).</Tip>

<Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

1. Navigate to the *Datasets* section under the *Annotate* heading.
2. Click the Dataset you want to attach data to.
3. Click **+Attach existing files**.

<div>
  <img />
</div>

4. Select the folders containing the files you want to attach to the Dataset. To select individual files, double-click a folder to see its contents, and select the files you want to add to the Dataset.

5. Click **Attach data** to attach the selected files to the Dataset.

***

### Create an Ontology

An Ontology is a structured framework that defines the categories, labels, and relationships used to annotate data consistently and accurately. Ontologies define what you want labeled.

<Note>We recommend learning about [Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) in Encord before creating Ontologies. </Note>

1. Click the **New ontology** button in the *Ontologies* section to create a new Ontology.

<div>
  <img />
</div>

2. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.

3. Click **Next** to continue.

<div>
  <img />
</div>

4. Define your Ontology structure. See our [documentation on Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) for more information on the various types of objects, classifications, and attributes.

**To add objects:**

<Warning>Ensure that you add *Audio Region* objects for audio files and *Text Region* objects for text files.</Warning>

<div>
  <img />
</div>

1. Click the **Add object** button.

2. Do one of the following:

   * Select a **Shared class**
   * Click **New Object**

   <Note>
     **Shared classes** cannot be edited while creating an Ontology. To edit a shared class go to the **Ontologies** > **Shared classes** page.
   </Note>

3. To create a new object, give the object a name. For example "Apple".

4. Select a shape for the object. For example *polygon*.

5. Optionally, enable the **Required** toggle to mark the object as *Required*.

6. Optionally, add attributes to the object.

7. Repeat these steps for as many objects as necessary.

**To add attributes to an object**:

You can add attributes to objects that define the object's characteristics. For example the object "Apple" can have an attribute "Color".

<div>
  <img />
</div>

1. Click the arrow icon next to an object to add attributes to the object.

2. Give the attribute a name. For example "Color".

3. Click the attribute type to change the attribute type. The default attribute type is a text field.

4. Click **Add option** to add an option, if you have chosen a radio button or checklist attribute.

5. Enter a name for the attribute option. For example, the attribute "Color" can have the options "Red", "Green", and "Yellow".

6. Click the **Back to parent** button to return the Ontology creation view.

**To add a classification**:

<div>
  <img />
</div>

1. Click **Add classification**.

2. Do one of the following:

   * Select a **Shared class**
   * Click **New classification**

   <Note>
     **Shared classes** cannot be edited while creating an Ontology. To edit a shared class go to the **Ontologies** > **Shared classes** page.
   </Note>

3. For a new classification, give the classification a name. For example, "Time of day".

4. Optionally, configure the classification. The default classification type is a text field.

5. Optionally, enable the **Required** toggle to mark the object as *Required*.

6. Repeat these steps for as many classifications as necessary.

**Configure classifications**:

You can configure classifications to change the classification type, and to add classification options to radio buttons and check lists.

<div>
  <img />
</div>

1. Click the arrow icon next to an object to configure the classification.

<div>
  <img />
</div>

2. Click the classification type to change the classification type. The default classification type is a text field.
3. Click **Add option** to add an option if you have selected a radio button or check list classification.
4. Enter a name for the classification option. For example, the classification "Time of day" can have the options "Night" and "Day".
5. Click the **Back to parent** button to return the Ontology creation view.

***

### Create a Custom Agent

Custom agents enable you to set up custom actions like pre-labeling, leveraging foundation models such as GPT-4, automated quality assurance, or other tailored actions to suit your Workflow.

Use the Encord SDK to configure your Advanced Custom Agent. The Agent executes the configured SDK script for all tasks that are routed through the Agent stage in your Workflow.

<AccordionGroup>
  <Accordion title="General Example">
    The General Example script shows how to configure a Workflow Agent with the name `Agent 1` and with a pathway called `continue to Review`.

    <Tip>Agent nodes can be used in conjunction with bundles to [efficiently handle bulk actions](/sdk-documentation/general-sdk/sdk-bulk-action-best-practices)</Tip>

    Ensure that you:

    * Replace `<private_key_path>` with the path to your private key.
    * Replace `<project_hash>` with the hash of your Project.
    * Insert your custom logic where the comment instructs you to do so.

    ```python General Example theme={"dark"}
    # Import dependencies
    from encord.user_client import EncordUserClient
    from encord.workflow import AgentStage

    # 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 that contains the agent. Replace <project_hash> with the hash of your Project
    project = user_client.get_project(<project_hash>)

    # Specify the Agent
    agent_stage = project.workflow.get_stage(name="Agent 1", type_=AgentStage)
    for task in agent_stage.get_tasks():

        # Now you have the agent task containing the data hash
        # Insert you custom logic here

    # When the custom logic is completed, the task can be moved forward to the selected pathway
    task.proceed(pathway_name="continue to Review")
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Pre-Classification of Images Using GPT 4o">
    ```mermaid theme={"dark"}
     sequenceDiagram
     participant AWS as AWS (Image Storage)
     participant Encord as Encord (Project)
     participant Agent as Agent Node (In Encord)
     participant Server as Your Server
     participant OpenAI as OpenAI

     AWS->>Encord: Send Signed Image URLs
     Encord->>Agent: Add Signed Image URL to Agent node
     Agent->>Server: Send Signed Image URL
     Server->>OpenAI: Send Image Data + Prompt
     OpenAI-->>Server: Return Classification
     Server->>Server: Transform Classification to Encord label structure
     Server->>Agent: Save Labels to Encord
     Agent->>Encord: Classification Saved to Label Row
     Encord->>Encord: Task Moved to Annotation Stage
    ```

    <Note> See our [end-to-end guide](/agents-documentation/Task-Agents/GPT4PreClassificationImages) for Pre-Classification using GPT 4o for more detailed information.</Note>

    The Pre-Classification script uses GPT 4o mini to route images to different annotation stages depending on what it is contained in the image. The Pre-Classification script applies to the following Workflow.

    <div>
      <img />
    </div>

    <Tip>Agent nodes can be used in conjunction with bundles to [efficiently handle bulk actions](/sdk-documentation/general-sdk/sdk-bulk-action-best-practices)</Tip>

    In the following script:

    * Replace `<private_key_path>` with the hash of your private key.
    * Replace `<project_hash>` with the hash of your Project.
    * Replace `Agent 1` with the name of your Agent stage.

    <CodeGroup>
      ```python Pre-Classification for Images Example theme={"dark"}
      # Import dependencies
      from encord.user_client import EncordUserClient
      from encord.workflow import AgentStage
      import openai
      import base64
      import requests
      import json

      # Initialize your OpenAI client
      openai.api_key = "<your_openai_api_key>"

      def get_classification_from_the_model(media_content):
          """
          Example function that passes media to OpenAI's ChatGPT API along with the prompt
          and parses the result.
          """
          prompt = """
          You are an image analysis expert. You're working on a project that includes annotation of different pets images.
          Your task is to assign one of the following tags to the image: "cat", "dog", "other".

          Reply in JSON format of the following structure: { "classification": cat|dog|other }
          """

          completion = openai.ChatCompletion.create(
              model="gpt-4o-mini",
              messages=[
                  ChatCompletionSystemMessageParam(role="system", content=prompt),
                  ChatCompletionUserMessageParam(
                      role="user",
                      content=[
                          ChatCompletionContentPartImageParam(
                              image_url=ImageURL(url=f"data:image/jpeg;base64,{media_content}", detail="auto"),
                              type="image_url",
                          )
                      ]
                  ),
              ],
              response_format=ResponseFormat(type="json_object"),
              max_tokens=1000,
          )

          raw_text_completion = completion.choices[0].message.content
          try:
              parsed_result = json.loads(raw_text_completion)
              return parsed_result["classification"].lower()
          except Exception as e:
              print(f"Failed to process the model response: {e}")
              return None


      # 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 that contains the agent. Replace <project_hash> with the hash of your Project
      project = user_client.get_project("<project_hash>")

      radio_classification = project.ontology_structure.get_child_by_title(
      title="Animal",
      type_=Classification,
      )

      cat_option = radio_ontology_classification.get_child_by_title(
      title="Cat", type_=Option
      )

      dog_option = radio_ontology_classification.get_child_by_title(
      title="Dog", type_=Option
      )

      # Specify the Agent
      agent_stage = project.workflow.get_stage(name="Agent 1", type_=AgentStage)

      for task in agent_stage.get_tasks():
          # Got a task for the following data unit
          print(f"{task.data_hash} -> {task.data_title}")

          # Getting a label row for the data unit
          label_row = project.list_label_rows_v2(data_hashes=[task.data_hash])[0]
          label_row.initialise_labels(include_signed_url=True)

          # Downloading the media:
          media_response = requests.get(label_row.data_link)
          media_content = base64.b64encode(media_response.content).decode("utf-8")

          # Now we can send the media to OpenAI:
          model_response = get_classification_from_the_model(media_content)

          # And interpret the result:
          match model_response:
              case "cat":

                  # Create a classification instance
                  classification_instance = (
                      radio_ontology_classification.create_instance()
                  )

                  radio_classification_instance.set_answer(
                      answer=cat_option
                  )
                  
                  label_row.add_classification_instance(radio_classification_instance)
                  label_row.save()

                  task.proceed(pathway_name="Cat")
              case "dog":

                  # Create & save classification instance
                  classification_instance = (
                      radio_ontology_classification.create_instance()
                  )
              
                  radio_classification_instance.set_answer(
                      answer=dog_option
                  )

                  
                  label_row.add_classification_instance(radio_classification_instance)
                  label_row.save()

                  task.proceed(pathway_name="Dog")
              case _:
                  task.proceed(pathway_name="Other")
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Pre-Labeling Videos Using a Mock Model">
    <Warning>
      This guide makes the following assumptions:

      * You have a model that takes video frames as an input and provides bounding box coordinates and confidence scores as an output.
      * You have installed the `encord-agents` library using the following command:

      ```
      python -m pip install encord-agents
      ```
    </Warning>

    The Pre-Labeling Script selects a random class from the Ontology, generates random bounding box labels, and applies random confidence scores for video frames before advancing the videos to the annotation stage (`Annotate 1`). Below is an example of a Workflow where the Pre-Labeling agent can be effectively utilized.

    <div>
      <img />
    </div>

    <Warning>
      To authenticate, you must set either of following environment variables in the environment that you plan to run your agents.

      * ENCORD\_SSH\_KEY: Containing the raw private key file content
      * ENCORD\_SSH\_KEY\_FILE: Containing the absolute path to the private key file
    </Warning>

    In the following script:

    * Replace `<project_hash>` with the hash of your Project.
    * Replace the mock model with your own model, and adapt the rest of the script according to your needs.
    * If you choose to give your python file a different name, ensure you replace all references to `prelabel_video.py` with your new file name.

    ```python prelabel_video.py theme={"dark"}
    #Import Dependencies
    import random
    from dataclasses import dataclass
    from typing import Iterable

    import numpy as np
    from encord.objects.coordinates import BoundingBoxCoordinates
    from encord.objects.ontology_labels_impl import LabelRowV2
    from encord.project import Project
    from encord_agents.core.data_model import Frame
    from encord_agents.tasks import Depends, Runner
    from encord_agents.tasks.dependencies import dep_video_iterator
    from numpy.typing import NDArray
    from typing_extensions import Annotated


    # Set the Environment variable to authenticate with Encord
    ENCORD_SSH_KEY_FILE="/path/to/file/" prelabel_video.py

    runner = Runner(project_hash="<project_hash>")

    # === BEGIN MOCK MODEL === #
    @dataclass
    class ModelPrediction:
        label: int
        coords: BoundingBoxCoordinates
        conf: float


    def fake_predict(image: NDArray[np.uint8]) -> list[ModelPrediction]:
        return [
            ModelPrediction(
                label=random.choice(range(3)),
                coords=BoundingBoxCoordinates(
                    top_left_x=random.random() * 0.5,
                    top_left_y=random.random() * 0.5,
                    width=random.random() * 0.5,
                    height=random.random() * 0.5,
                ),
                conf=random.random() + 0.5,
            )
            for _ in range(10)
        ]


    model = fake_predict
    # === END MOCK MODEL === #

    @runner.stage(stage="Pre-Labeling Agent")
    def run_something(
        lr: LabelRowV2,
        project: Project,
        frames: Annotated[Iterable[Frame], Depends(dep_video_iterator)],
    ) -> str:
        ontology = project.ontology_structure

        # Create an object instance for each frame in the video and save the labels. 
        for frame in frames:
            outputs = model(frame.content)
            for output in outputs:
                ins = ontology.objects[output.label].create_instance()
                ins.set_for_frames(
                    frames=frame.frame, coordinates=output.coords, confidence=output.conf
                )

                lr.add_object_instance(ins)

        lr.save()

        # Return the name of the stage the task should progress to
        return "Annotate 1"  


    if __name__ == "__main__":
        runner.run()
    ```
  </Accordion>
</AccordionGroup>

## Repeatable Ontology Feature Requirements

Some agent templates support **repeatable** Ontology feature requirements, which allow you to assign multiple ontology features to a single role. This is useful for agents that need to operate across several classes simultaneously, for example, a merge-object-classes agent that combines multiple source classes into one.

### Selecting features for a repeatable requirement

When an agent template declares a requirement as repeatable, the configuration form displays a **multi-select tree picker** instead of the standard single-select picker.

<Note>The multi-select tree picker only appears for requirements that the agent template has marked as repeatable. Requirements that are not repeatable continue to use the standard single-select behavior.</Note>

* Select as many Ontology features as the requirement allows by clicking each feature in the tree picker.
* The form enforces a **minimum** number of selections. You cannot submit the form until you have selected at least the required number of features. If you select too few, the form displays the message: *"Please select at least N features"*.
* If the template defines a **maximum** number of selections, the picker prevents you from selecting additional features once the maximum is reached.

### How selected features appear in the agent detail view

After you save the agent, the detail view groups all features selected for a repeatable requirement under a single label. For example, if you selected **ClassA** and **ClassB** for a role called **Source Object Classes**, the detail view displays:

**Source Object Classes:** `ClassA` `ClassB`

### Ontology compatibility and repeatable requirements

When you select an ontology during agent creation, Encord automatically filters out ontologies that do not contain enough eligible features to satisfy the minimum selection count for any repeatable requirement. Only ontologies with a sufficient number of matching features appear in the Ontology selector.

***

### Create a Workflow

*Workflows* allow you to design and manage the flow of tasks through various stages of a Project. You have control over how tasks progress and how different stages interact.

<AccordionGroup>
  <Accordion title="Video tutorial - Creating workflow templates">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

To set up a Workflow template, navigate to the Project section of the Encord platform and select the **Templates** tab.

<div>
  <img />
</div>

**1. Add users to the Workflow**:

Add users from your [Workspace](/platform-documentation/General/general-workspace-settings) to the Workflow by clicking **Invite collaborators**.

<div>
  <img />
</div>

* Collaborators are added based on their role within the project - select the role you would like the collaborator(s) to have.
* Start typing the email of a user you would like to add into the area highlighted on the image below, and select the user from the list that appears. Repeat this for every user that will have the same role.
* When you are done selecting users for this role, click **Add**.

<div>
  <img />
</div>

<Note>Learn more about managing collaborators in the [Managing collaborators](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#managing-collaborators) section.</Note>

**2. Configure your Workflow**:

The canvas is populated with a simple Workflow by default.

Click the **Add stage** button to show all Workflow components.

<div>
  <img />
</div>

Customize your Workflow by pulling components onto the canvas.

<div>
  <img />
</div>

Add the stages and other components you require for your Workflow onto the canvas:

* All workflows must begin with the [**Start**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#start) stage.

* All workflows must contain an [**Annotate**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate) stage.

* Add [routers](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#routers) to your Project to determine different pathways through your Workflow a task can take.

* Add as many [**Review**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#review) stages as necessary.

* All workflows must end at a [**Complete**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#complete) stage.

* Link all components on the canvas by clicking and dragging from one connection point to another.

<div>
  <img />
</div>

All Workflows can be saved as a [template](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates) by clicking the **Save as a new template** button.

<div>
  <img />
</div>

**3. Configure the stages of your Workflow**:

After you arranged the stages in the composer, it is time to configure the details of each stage.

* Click an **Annotate** card on the canvas to start editing the [annotation stage](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate).
  * Give the stage a descriptive name.
  * Add annotators. If you'd like to specify annotators for this stage, add them as collaborators. For full details on how collaborators can work on tasks at each stage, see our section on [managing collaborators](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#managing-collaborators).
  * Optionally, add a [Webhook](/platform-documentation/Annotate/annotate-webhooks-notifications) to receive notifications when labels are submitted at this stage.

<Note>More details about configuring annotation stages can be found in the [**Annotate** section](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate) below</Note>

* Click a **Review** card on the canvas to start editing the [review stage](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#review).
  * Give the stage a descriptive name.
  * Add reviewers. If you want to specify reviewers for this stage, add them as collaborators. For full details on how collaborators can work on tasks at each stage, see our section on [managing collaborators](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#managing-collaborators).

<Note>More details about configuring review stages can be found in the [**Review** section](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#review) below.</Note>

* Click a **Router** card on your canvas. See the [router section](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#routers) for more details on how different types of routers can be configured.

* Optionally, add a Webhook to the **Complete** stage to receive a notification when a task has been completed.

* Optionally, add [*User assignment restrictions*](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#user-assignment-restriction) if users in this node should be prevented from being assigned to tasks they completed in the nodes listed.

<Note>More details on routers can be found in the [router section](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#routers) below.</Note>

### Create a Project

Projects in Encord bring together Datasets, Ontologies, and Workflows. Datasets are labeled according to the Ontology, while the Workflow defines how tasks progress through the Project from start to finish.

<Note>
  Projects only require a **Title** to be saved.
</Note>

<iframe title="YouTube video player" />

1. Select **Projects** in the Encord platform.

2. Click the **+ New annotation project** button or use <kbd>CONTROL</kbd> / <kbd>CMD</kbd>  + <kbd>ENTER</kbd> to create a new Project.

3. Give the Project a meaningful title and description.

<Note>
  If you are part of an [Workspace](/platform-documentation/General/general-workspace-settings), an optional [Project tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags) drop-down is visible. Project tags are useful for categorizing and finding your Projects. Select as many tags as are relevant for your Project.
</Note>

4. Apply any meaningful [**Project tags**](/platform-documentation/General/general-workspace-settings#project-tags) you need to the Project.

5. Specify the Workflow you want to use for the Project.

6. Click the **Templates** > **Load from template** to use a [Workflow template](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates).

7. Select the template you want to use and click **Load template**.

8. Click the **Ontology** button.

9. Select an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) from the list, or [create a new Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies) by clicking the **New ontology** button.

10. Click the **Data** button.

11. Select one or more data sources from the list.

12. Click **Collaborators**.

13. Specify the users and the roles they have in the Project.

14. Click **Create project** to finish creating the Project.

#### Add users to the Project

After creating a Project, invite users to act as annotators, reviewers, team managers, and admins. Collaborators can be added as individuals, or as part of [user groups](/platform-documentation/General/general-workspace-settings#user-groups).

<AccordionGroup>
  <Accordion title="Invite individuals">
    1. Navigate to **Projects** in the Encord app.

    <div>
      <img />
    </div>

    2. Select the Project you want to add users to.

    3. Navigate to the *Settings* tab.

    4. Navigate to the *Team* pane.

    5. Click **Invite collaborators**.

    <div>
      <img />
    </div>

    6. Select the desired role for the users.

    7. Enter the users' email addresses and choose the users to assign the selected role.

    8. Click **Add** to include the selected users in the Project.

    <div>
      <img />
    </div>

    9. Repeat this process for each required user role.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Invite user groups">
    <Info>To invite [user groups](/platform-documentation/General/general-workspace-settings#user-groups) your Workspace must have user groups.</Info>

    1. Navigate to **Projects** in the Encord app.

    <div>
      <img />
    </div>

    2. Select the Project you want to add users to.

    3. Navigate to the *Settings* tab.

    4. Navigate to the *Team* pane.

    5. Select the *Groups* tab.

    6. Click **Manage**.

    <div>
      <img />
    </div>

    7. Select a group from the dropdown.

    8. Select the role you want the user group to have.

    9. Click **Add** to add the user group to the Project.

    <div>
      <img />
    </div>

    10. Repeat this process for each required user group and role.
  </Accordion>
</AccordionGroup>

## STEP 3: Label your Data

Now you are ready to label your data. We recommend you and your team watch these introductory videos.

<Tip>For more details, see our comprehensive [tutorial on labeling here](/platform-documentation/GettingStarted/gettingstarted-labeling).</Tip>

<AccordionGroup>
  <Accordion title="Video tutorial - Introduction to image annotation">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Video tutorial - Introduction to video annotation">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

## STEP 4: Export your Labels

<Info>Only Project admins can export labels</Info>

<Tip>Descriptions of all information contained in the export file can be found [in the export file reference](/platform-documentation/Annotate/annotate-export/annotate-export-json).</Tip>

<iframe title="YouTube video player" />

<Tip>
  To export labels for specific tasks:

  1. Select the tasks
  2. Click **Bulk actions**
  3. Select **Export**
</Tip>

1. Click **Export** while in a Project.

   The *Export labels* dialog appears.

2. Specify the following:
   * **Format:** Specify the format to export the labels (JSON or COCO).
   * **Stage:** Specify the Workflow stage to export the labels from.
   * **Generate signed URLs:** Specify whether to generate signed URLs for the data units that have labels.
   <Note>
     Enabling this option can significantly increase export times.
   </Note>
   * **Save as new version:** Specify to version the labels.
     * Provide a meaningful name for the label version.
   * **Labels to include:** Specify the labels to include. You can export all labels or select specific object or classification labels to export.

3. Click **Export**.

   A *Labels export in progress* toast message appears.


# Data Curation, Management, and Annotation
Source: https://docs.encord.com/end-to-end/GettingStartedE2E/data-curation-management-annotation



<div>
  <img />
</div>

***

## STEP 1: Register Your Files With Encord

### Create a Cloud Integration

Select your cloud provider.

<div lang="en">
  <head>
    <meta />

    <meta name="viewport" />

    <title>Clickable Div</title>
  </head>

  <div>
    <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration">
      AWS Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration">
      GCP Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration">
      Azure Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-otc-integration">
      OTC Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-wasabi-integration">
      Wasabi Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-oracle-integration">
      Oracle Integration
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-direct-access-integration">
      Direct Access Integration
    </a>
  </div>
</div>

***

### Create Metadata Schema

Based on your Data Discoverability Strategy, you need to create a metadata schema. The schema provides a method of organization for your custom metadata. Encord supports:

* Scalars: Methods for filtering.
* Enums: Methods with options for filtering.
* Embeddings: Method for embedding plot visualization, similarity search, and natural language search.

<Tip>Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and the following blank spaces ( ), hyphens (-), underscores (\_), and periods (.).</Tip>

### Metadata schema table

<Tip>Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and blank spaces ( ), hyphens (-), underscores (\_), and periods (.). Metadata schema keys are case sensitive.</Tip>

Use `add_scalar` to add a scalar key to your metadata schema.

| Scalar Key | Description                                                                                                                                                                                | Display Benefits                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| boolean    | Binary data type with values "true" or "false".                                                                                                                                            | Filtering by binary values                        |
| datetime   | ISO 8601 formatted date and time.                                                                                                                                                          | Filtering by time and date                        |
| number     | Numeric data type supporting float values.                                                                                                                                                 | Filtering by numeric values                       |
| uuid       | UUIDv4 formatted unique identifier for a data unit.                                                                                                                                        | Filtering by customer specified unique identifier |
| varchar    | Textual data type. Formally `string`. `string` can be used as an alias for `varchar`, but we STRONGLY RECOMMEND that you use `varchar`.                                                    | Filtering by string.                              |
| text       | Text data with unlimited length (example: transcripts for audio). Formally `long_string`. `long_string` can be used as an alias for `text`, but we STRONGLY RECOMMEND that you use `text`. | Storing and filtering large amounts of text.      |

Use `add_enum` and `add_enum_options` to add an enum and enum options to your metadata schema.

| Key  | Description                                    | Display Benefits                                      |
| ---- | ---------------------------------------------- | ----------------------------------------------------- |
| enum | Enumerated type with predefined set of values. | Facilitates categorical filtering and data validation |

Use `add_embedding` to add an embedding to your metadata schema.

| Key       | Description                                | Display Benefits                                                                        |
| --------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
| embedding | 1 to 4096 for Index. 1 to 2000 for Active. | Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon) |

Use `add_geospatial` to add a new geospatial type to the metadata schema.

| Key        | Description                                                                                                                                                                        | Display Benefits                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| geospatial | Geospatial data that contains latitude and longitude information. Latitude values are between +90 (North) to -90 (South). Longitude values are between +180 (West) to -180 (East). | Filtering data by using a geospatial map. |

<Note>
  * Geospatial custom metadata is supported only in Index.

  * Geospatial custom metadata can be applied to all data unit types and on individual frames in videos.
</Note>

<Warning>
  Incorrectly specifying a data type in the schema can cause errors when filtering your data in Index or Active. If you encounter errors while filtering, verify your schema is correct. If your schema has errors, correct the errors, re-import the schema, and then re-sync your Active Project.
</Warning>

### Import your metadata schema to Encord

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("metadata_1", data_type="boolean")
  metadata_schema.add_scalar("metadata_2", data_type="datetime")
  metadata_schema.add_scalar("metadata_3", data_type="number")
  metadata_schema.add_scalar("metadata_4", data_type="uuid")
  metadata_schema.add_scalar("metadata_5", data_type="varchar")
  metadata_schema.add_scalar("metadata_6", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("my-enum", values=["enum-value-01", "enum-value-02", "enum-value-03"])

  # Add embedding fields
  metadata_schema.add_embedding("my-test-active-embedding", size=512)
  metadata_schema.add_embedding("my-test-index-embedding", size=<values-from-1-to-4096>)

  # Add geospatial
  metadata_schema.add_geospatial("geo-point")

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("G2G", data_type="boolean")
  metadata_schema.add_scalar("Date", data_type="datetime")
  metadata_schema.add_scalar("Cost", data_type="number")
  metadata_schema.add_scalar("Priority", data_type="number")
  metadata_schema.add_scalar("ID-Sys-01", data_type="uuid")
  metadata_schema.add_scalar("ID-Sys-02", data_type="uuid")
  metadata_schema.add_scalar("Description", data_type="varchar")
  metadata_schema.add_scalar("Location", data_type="varchar")
  metadata_schema.add_scalar("Address", data_type="varchar")
  metadata_schema.add_scalar("Translation en-gb", data_type="text")
  metadata_schema.add_scalar("Translation en-ca", data_type="text")
  metadata_schema.add_scalar("Translation en-us", data_type="text")
  metadata_schema.add_scalar("Translation zh-tw", data_type="text")
  metadata_schema.add_scalar("Translation zh-hk", data_type="text")
  metadata_schema.add_scalar("Translation zh-cn", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("ready", values=["ripe", "partially-ripe", "unripe"])
  metadata_schema.add_enum("Fruit", values=["Blueberries", "Cherries", "Apples", "Kiwi"])

  # Add embedding fields
  metadata_schema.add_embedding("active-embedding-01", size=512)
  metadata_schema.add_embedding("active-embedding-02", size=512)
  metadata_schema.add_embedding("index-embedding-100", size=100)
  metadata_schema.add_embedding("index-embedding-1000", size=1000)

  # Add geospatial
  metadata_schema.add_geospatial("Coordinates")

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

### Verify your schema

After importing your schema to Encord we recommend that you verify that the import is successful. Run the following code to verify your metadata schema imported and that the schema is correct.

<CodeGroup>
  ```python Verify schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Verify your schema example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

***

### Create a Folder

You must create a folder in Index to store your files.

1. Navigate to **Data** > **Files & Folders**
2. Click the **+ New folder** button to create a new folder. Select the type of folder you want to create.

<div>
  <img />
</div>

3. Give the folder a meaningful name and description.

4. Click **Create** to create the folder.
   The folder is listed in **Files & Folders**.

***

### Create JSON or CSV for Registration

To import files from cloud storage into Encord, you must create a JSON or CSV file specifying the files you want to register.

<Tip>
  Find helpful scripts for creating JSON and CSV files for the data registration process [here](/platform-documentation/Curate/add-files/index-register-cloud-data#helpful-scripts-and-examples).
</Tip>

All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

<Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data)</Note>

<Info>Encord supports file names up to 300 characters in length for any file or video for upload.</Info>

<Info>
  Encord enforces the following upload limits for each JSON file used for file registration:

  * Up to 1 million URLs
  * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  * URLs can be up to 16 KB in size

  Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
</Info>

<Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

<AccordionGroup>
  <Accordion title="JSON Format">
    #### Create JSON file for Registration

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

    <Note>If `skip_duplicate_urls` is set to `true`, all object URLs that exactly match existing images/videos in the dataset are skipped.</Note>

    <Accordion title="JSON for AWS">
      #### AWS JSON

      <AccordionGroup>
        <Accordion title="Videos">
          #### [Videos](#videos)

          **Video Metadata**

          When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

          <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "cloud-path-to-your-video-1"
                },
                {
                  "objectUrl": "cloud-path-to-your-video-2",
                    "videoMetadata": {
                      "fps": frames-per-second,
                      "duration": duration-in-seconds,
                      "width": frame-width,
                      "height": frame-height,
                      "file_size": file-size-in-bytes,
                      "mime_type": "MIME-file-type-extension"
                    }
                  }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/BerghouseLeopardJog.mp4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blue_bus_video.mp4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/bluemlisalphutte_flyover.mp4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake_normalized.mp4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/snow_sled.MOV"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cyclists.MP4"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Video Metadata theme={"dark"}
            {
                "videos": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/video_file.mp4",
                    "videoMetadata": {
                        "fps": 23.98,
                        "duration": 29.09,
                        "width": 1280,
                        "height": 720,
                        "file_size": 5468354,
                        "mime_type": "video/mp4"
                    }
                  }
                ],
              "skip_duplicate_urls": true
              }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Audio files">
          #### [Audio Files](#audio-files)

          The following is an example JSON file for uploading two audio files to Encord.

          <Tip>
            Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
          </Tip>

          * **Template:** Imports audio files with an Encord title.
          * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "audio": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-custom-audio-file-title.mp3"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Audio Metadata theme={"dark"}
            {
                "audio": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file.mp3",
                    "audioMetadata": {
                        "duration": 23.98,
                        "file_size": 2900000,
                        "mime_type": "audio/mp3",
                        "sample_rate": 44100,
                        "bit_depth": 24,
                        "codec": "mp3",
                        "num_channels": 2
                    }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="PDFs">
          #### [PDFs](#pdfs)

          The following are example JSON files for uploading PDFs to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "pdfs": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-document-02.pdf"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-document-03.pdf",
                  "pdfMetadata": {
                    "fileSize": 300,
                    "numPages": 5
                    }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "pdfs": [
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-01.pdf",

                  },
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-02.pdf",
                    "title": "my-document-02.pdf"
                  },
                  {
                    "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-03.pdf",
                    "title": "my-document-03.pdf",
                    "pdfMetadata": {
                      "fileSize": 300,
                      "numPages": 5
                      }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Text Files">
          #### [Text Files](#text-files)

          The following are example JSON files for uploading text files to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "text": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-file.html"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-plain-text-file.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "<object url_4>",
                  "title": "my-csv-file.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "<object url_5>",
                  "title": "my-xml-file.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "<object url_6>",
                  "title": "my-html-file.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "text": [
                  {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-file-01.html"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-01.txt",
                  "title": "my-plain-text-file-01.txt"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-02.txt",
                  "title": "my-plain-text-file-02.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-csv-file-01.csv",
                  "title": "my-csv-file-01.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-xml-file-01.xml",
                  "title": "my-xml-file-01.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-html-file-01.html",
                  "title": "my-html-file-01.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Single images">
          #### [Single Images](#single-images)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          The JSON structure for single images parallels that of videos.

          **Template:** Provides the proper JSON format to import images into Encord.

          **Examples:**

          * **Data** Imports the images only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "file/path/to/images/file-name-01.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-02.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-03.file-extension",
                  "title": "image-title.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data    theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.jpg"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0003.jpg"
                },
                {
                  "objectUrl": "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"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                },
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/large_images/pexels-ivo-rainha-00057.png"
                }
              ]
            }
            ```

            ```json Image Metadata theme={"dark"}

            {
              "images": [
                {
                  "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/my_image.jpg",
                  "imageMetadata": {
                    "mimeType": "image/jpg",
                    "fileSize": 124,
                    "width": 640,
                    "height": 480
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image groups">
          #### [Image groups](#image-groups)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image groups are collections of images that are processed as one annotation task.
          * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
          * Image groups do NOT require 'write' permissions to your cloud storage.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the image groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "image_groups": [
                {
                  "title": "<title 1>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                },
                {
                  "title": "<title 2>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image group 01",
                  "createVideo": false,
                  "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg",
                  "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.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 group 02",
                  "createVideo": false,
                  "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0001.jpg",
                  "objectUrl_1": "<https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0002.jpg",
                  "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0003.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image sequences">
          #### [Image sequences](#image-sequences)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image sequences are collections of images that are processed as one annotation task and represented as a video.
          * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
          * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
          * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

          <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the images groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "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>"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "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
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="DICOM">
          #### [DICOM](#dicom)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Each `dicom_series` element can contain one or more DICOM series.
          * Each series requires a title and at least one object URL, as shown in the example below.
          * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

          <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

          The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

          * The first series contains only a single object URL, as it is composed of a single file.
          * The second series contains 3 object URLs, as it is composed of three separate files.
          * The third series contains 2 object URLs, as it is composed of two separate files.

          <Info>
            For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
          </Info>

          ```json Template theme={"dark"}
          {
            "dicom_series": [
              {
                "title": "Series-1",
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series1-file.dcm"
              },
              {
                "title": "Series-2",
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file1.dcm",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file2.dcm",
                "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file3.dcm",
              },
                {
                "title": "Series-3",
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file1.dcm",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file2.dcm",
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="NIfTI">
          #### [NIfTI](#nifti)

          The following is an example JSON file for uploading two NIfTI files to Encord.

          ```json Template theme={"dark"}
          {
              "nifti": [
                {
                  "title": "<file-1>",
                  "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                },
                {
                  "title": "<file-2>",
                  "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                }
              ],
              "skip_duplicate_urls": true
            }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title=" Multiple file types ">
          You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

          ```json Multiple file types theme={"dark"}

          {
            "images": [
              {
                "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/Image1.png"
              }
            ],
            "videos": [
              {
                "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Cooking.mp4"
              },
              {
                "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Oranges.mp4"
              }
            ],
            "image_groups": [
              {
                "title": "apple-samsung-light",
                "createVideo": true,
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(32).jpg",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
                "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
                "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
              },
              {
                "title": "apple-samsung-dark",
                "createVideo": true,
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(32).jpg",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(33).jpg",
                "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(34).jpg",
                "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(35).jpg"
              }
            ],
            "image_groups": [
              {
                "title": "apple-ios-light",
                "createVideo": false,
                "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(32).jpg",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(33).jpg"
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    <Accordion title="JSON for GCP">
      #### GCP JSON

      <AccordionGroup>
        <Accordion title="Videos">
          #### [Videos](#videos)

          **Video Metadata**

          When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

          <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "cloud-path-to-your-video-1"
                },
                {
                  "objectUrl": "cloud-path-to-your-video-2",
                    "videoMetadata": {
                      "fps": frames-per-second,
                      "duration": duration-in-seconds,
                      "width": frame-width,
                      "height": frame-height,
                      "file_size": file-size-in-bytes,
                      "mime_type": "MIME-file-type-extension"
                    }
                  }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/eLeopardJog.mp4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/_video.mp4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/bluemlisalphutte_flyover.mp4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake_normalized.mp4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/snow_sled.MOV"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/cyclists.MP4"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Video Metadata theme={"dark"}
            {
                "videos": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/video_file.mp4",
                    "videoMetadata": {
                        "fps": 23.98,
                        "duration": 29.09,
                        "width": 1280,
                        "height": 720,
                        "file_size": 5468354,
                        "mime_type": "video/mp4"
                    }
                  }
                ],
                "skip_duplicate_urls": true
              }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Audio files">
          #### [Audio Files](#audio-files)

          The following is an example JSON file for uploading two audio files to Encord.

          <Tip>
            Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
          </Tip>

          * Example 1 imports audio files with an Encord title.
          * Example 2 imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "audio": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-custom-audio-file-title.mp3"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Audio Metadata theme={"dark"}
            {
                "audio": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/audio_file.mp3",
                    "audioMetadata": {
                        "duration": 23.98,
                        "file_size": 2900000,
                        "mime_type": "audio/mp3",
                        "sample_rate": 44100,
                        "bit_depth": 24,
                        "codec": "mp3",
                        "num_channels": 2
                    }
                  }
                ],
                "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="PDFs">
          #### [PDFs](#pdfs)

          The following are example JSON files for uploading PDFs to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "pdfs": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-document-02.pdf"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-document-03.pdf",
                  "pdfMetadata": {
                    "fileSize": 300,
                    "numPages": 5
                    }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "pdfs": [
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-01.pdf",

                  },
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-02.pdf",
                    "title": "my-document-02.pdf"
                  },
                  {
                    "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-03.pdf",
                    "title": "my-document-03.pdf",
                    "pdfMetadata": {
                      "fileSize": 300,
                      "numPages": 5
                      }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Text Files">
          #### [Text Files](#text-files)

          The following are example JSON files for uploading text files to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "text": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-file.html"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-plain-text-file.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "<object url_4>",
                  "title": "my-csv-file.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "<object url_5>",
                  "title": "my-xml-file.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "<object url_6>",
                  "title": "my-html-file.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "text": [
                  {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-file-01.html"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-01.txt",
                  "title": "my-plain-text-file-01.txt"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-02.txt",
                  "title": "my-plain-text-file-02.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-csv-file-01.csv",
                  "title": "my-csv-file-01.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-xml-file-01.xml",
                  "title": "my-xml-file-01.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-html-file-01.html",
                  "title": "my-html-file-01.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Single images">
          #### [Single Images](#single-images)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          The JSON structure for single images parallels that of videos.

          **Template:** Provides the proper JSON format to import images into Encord.

          **Examples:**

          * **Data** Imports the images only.

          * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "file/path/to/images/file-name-01.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-02.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-03.file-extension",
                  "title": "image-title.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/0001.jpg"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0003.jpg"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                },
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/large_images/pexels-ivo-rainha-00057.png"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Image Metadata theme={"dark"}

            {
              "images": [
                {
                  "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/my_image.jpg",
                  "imageMetadata": {
                    "mimeType": "image/jpg",
                    "fileSize": 124,
                    "width": 640,
                    "height": 480
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image groups">
          #### [Image groups](#image-groups)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image groups are collections of images that are processed as one annotation task.
          * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
          * Image groups do NOT require 'write' permissions to your cloud storage.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the image groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "image_groups": [
                {
                  "title": "<title 1>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                },
                {
                  "title": "<title 2>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image group 01",
                  "createVideo": false,
                  "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/0001.jpg",
                  "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg",
                  "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "title": "Image group 02",
                  "createVideo": false,
                  "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0001.jpg",
                  "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-0002.jpg",
                  "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0003.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image sequences">
          #### [Image sequences](#image-sequences)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image sequences are collections of images that are processed as one annotation task and represented as a video.
          * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
          * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
          * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

          <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the images groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "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>"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image sequence 001",
                  "createVideo": true,
                  "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/01.jpg",
                  "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/02.jpg",
                  "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/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://storage.cloud.google.com/encord-image-bucket/images/thing-01.jpg",
                  "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-02.jpg",
                  "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-03.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="DICOM">
          #### [DICOM](#dicom)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Each `dicom_series` element can contain one or more DICOM series.
          * Each series requires a title and at least one object URL, as shown in the example below.
          * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

          <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

          The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

          * The first series contains only a single object URL, as it is composed of a single file.
          * The second series contains 3 object URLs, as it is composed of three separate files.
          * The third series contains 2 object URLs, as it is composed of two separate files.

          <Info>
            For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
          </Info>

          ```json JSON for DICOM theme={"dark"}
          {
            "dicom_series": [
              {
                "title": "Series-1",
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series1-file.dcm"
              },
              {
                "title": "Series-2",
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file1.dcm",
                "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file2.dcm",
                "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file3.dcm",
              },
                {
                "title": "Series-3",
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file1.dcm",
                "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file2.dcm",
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="NIfTI">
          #### [NIfTI](#nifti)

          The following is an example JSON file for uploading two NIfTI files to Encord.

          ```json theme={"dark"}
          {
              "nifti": [
                {
                  "title": "<file-1>",
                  "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                },
                {
                  "title": "<file-2>",
                  "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                }
              ],
              "skip_duplicate_urls": true
            }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title=" Multiple file types ">
          You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

          ```json Multiple file types theme={"dark"}

          {
            "images": [
              {
                "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/Image1.png"
              }
            ],
            "videos": [
              {
                "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Cooking.mp4"
              },
              {
                "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Oranges.mp4"
              }
            ],
            "image_groups": [
              {
                "title": "apple-samsung-light",
                "createVideo": true,
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/1+(32).jpg",
                "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
                "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
                "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
              },
              {
                "title": "apple-samsung-dark",
                "createVideo": true,
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/2+(32).jpg",
                "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/2+(33).jpg",
                "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/2+(34).jpg",
                "objectUrl_3": "https://storage.cloud.google.com/encord-image-bucket/images/2+(35).jpg"
              }
            ],
            "image_groups": [
              {
                "title": "apple-ios-light",
                "createVideo": false,
                "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/3+(32).jpg",
                "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/3+(33).jpg"
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    <Accordion title="JSON for Azure">
      #### Azure JSON

      <AccordionGroup>
        <Accordion title="Videos">
          #### [Videos](#videos)

          **Video Metadata**

          When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

          <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "cloud-path-to-your-video-1"
                },
                {
                  "objectUrl": "cloud-path-to-your-video-2",
                    "videoMetadata": {
                      "fps": frames-per-second,
                      "duration": duration-in-seconds,
                      "width": frame-width,
                      "height": frame-height,
                      "file_size": file-size-in-bytes,
                      "mime_type": "MIME-file-type-extension"
                    }
                  }
                {
                  "objectUrl": "cloud-path-to-your-video-3",
                  "title": "title-for-your-video-3"

                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/BerghouseLeopardJog.mp4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/blue_bus_video.mp4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/bluemlisalphutte_flyover.mp4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake_normalized.mp4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/snow_sled.MOV"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/cyclists.MP4"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Video Metadata theme={"dark"}
            {
                "videos": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/video_file.mp4",
                    "videoMetadata": {
                        "fps": 23.98,
                        "duration": 29.09,
                        "width": 1280,
                        "height": 720,
                        "file_size": 5468354,
                        "mime_type": "video/mp4"
                    }
                  }
                ],
                "skip_duplicate_urls": true
              }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Audio files">
          #### [Audio Files](#audio-files)

          The following is an example JSON file for uploading two audio files to Encord.

          <Tip>
            Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
          </Tip>

          * **Template:** Imports audio files with an Encord title.
          * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "audio": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-custom-audio-file-title.mp3"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Audio Metadata theme={"dark"}
            {
                "audio": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/audio_file.mp3",
                    "audioMetadata": {
                        "duration": 23.98,
                        "file_size": 2900000,
                        "mime_type": "audio/mp3",
                        "sample_rate": 44100,
                        "bit_depth": 24,
                        "codec": "mp3",
                        "num_channels": 2
                    }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="PDFs">
          #### [PDFs](#pdfs)

          The following are example JSON files for uploading PDFs to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "pdfs": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-document-02.pdf"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-document-03.pdf",
                  "pdfMetadata": {
                    "fileSize": 300,
                    "numPages": 5
                    }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "pdfs": [
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-01.pdf",

                  },
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-02.pdf",
                    "title": "my-document-02.pdf"
                  },
                  {
                    "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-03.pdf",
                    "title": "my-document-03.pdf",
                    "pdfMetadata": {
                      "fileSize": 300,
                      "numPages": 5
                      }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Text Files">
          #### [Text Files](#text-files)

          The following are example JSON files for uploading text files to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "text": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-file.html"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-plain-text-file.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "<object url_4>",
                  "title": "my-csv-file.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "<object url_5>",
                  "title": "my-xml-file.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "<object url_6>",
                  "title": "my-html-file.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "text": [
                  {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-file-01.html"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-01.txt",
                  "title": "my-plain-text-file-01.txt"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-02.txt",
                  "title": "my-plain-text-file-02.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-csv-file-01.csv",
                  "title": "my-csv-file-01.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-xml-file-01.xml",
                  "title": "my-xml-file-01.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-html-file-01.html",
                  "title": "my-html-file-01.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Single images">
          #### [Single Images](#single-images)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          The JSON structure for single images parallels that of videos.

          **Template:** Provides the proper JSON format to import images into Encord.

          **Examples:**

          * **Data** Imports the images only.

          * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "file/path/to/images/file-name-01.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-02.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-03.file-extension",
                  "title": "image-title.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0003.jpg"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                },
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/large_images/pexels-ivo-rainha-00057.png"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Image Metadata theme={"dark"}

            {
              "images": [
                {
                  "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my_image.jpg",
                  "imageMetadata": {
                    "mimeType": "image/jpg",
                    "fileSize": 124,
                    "width": 640,
                    "height": 480
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image groups">
          #### [Image groups](#image-groups)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image groups are collections of images that are processed as one annotation task.
          * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
          * Image groups do NOT require 'write' permissions to your cloud storage.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the image groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "image_groups": [
                {
                  "title": "<title 1>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                },
                {
                  "title": "<title 2>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image group 01",
                  "createVideo": false,
                  "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg",
                  "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg",
                  "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "title": "Image group 02",
                  "createVideo": false,
                  "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0001.jpg",
                  "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0002.jpg",
                  "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-0003.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image sequences">
          #### [Image sequences](#image-sequences)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image sequences are collections of images that are processed as one annotation task and represented as a video.
          * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
          * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
          * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

          <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the images groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "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>"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image sequence 001",
                  "createVideo": true,
                  "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/01.jpg",
                  "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/02.jpg",
                  "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/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://myaccount.blob.core.windows.net/encordcontainer/thing-01.jpg",
                  "objectUrl_1": "<https://myaccount.blob.core.windows.net/encordcontainer/thing-02.jpg",
                  "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-03.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="DICOM">
          #### [DICOM](#dicom)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Each `dicom_series` element can contain one or more DICOM series.
          * Each series requires a title and at least one object URL, as shown in the example below.
          * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

          <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

          The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

          * The first series contains only a single object URL, as it is composed of a single file.
          * The second series contains 3 object URLs, as it is composed of three separate files.
          * The third series contains 2 object URLs, as it is composed of two separate files.

          <Info>
            For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
          </Info>

          ```json Template theme={"dark"}
          {
            "dicom_series": [
              {
                "title": "Series-1",
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series1-file.dcm"
              },
              {
                "title": "Series-2",
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file1.dcm",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file2.dcm",
                "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file3.dcm",
              },
                {
                "title": "Series-3",
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file1.dcm",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file2.dcm",
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="NIfTI">
          #### [NIfTI](#nifti)

          The following is an example JSON file for uploading two NIfTI files to Encord.

          ```json Template theme={"dark"}
          {
              "nifti": [
                {
                  "title": "<file-1>",
                  "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                },
                {
                  "title": "<file-2>",
                  "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                }
              ],
              "skip_duplicate_urls": true
            }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title=" Multiple file types ">
          You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

          ```json theme={"dark"}

          {
            "images": [
              {
                "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Image1.png"
              }
            ],
            "videos": [
              {
                "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Cooking.mp4"
              },
              {
                "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Oranges.mp4"
              }
            ],
            "image_groups": [
              {
                "title": "apple-samsung-light",
                "createVideo": true,
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(32).jpg",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(33).jpg",
                "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(34).jpg",
                "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(35).jpg"
              },
              {
                "title": "apple-samsung-dark",
                "createVideo": true,
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(32).jpg",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(33).jpg",
                "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(34).jpg",
                "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(35).jpg"
              }
            ],
            "image_groups": [
              {
                "title": "apple-ios-light",
                "createVideo": false,
                "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(32).jpg",
                "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(33).jpg"
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    <Accordion title="JSON for OTC">
      #### OTC JSON

      <AccordionGroup>
        <Accordion title="Videos">
          #### [Videos](#videos)

          **Video Metadata**

          When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

          <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "cloud-path-to-your-video-1"
                },
                {
                  "objectUrl": "cloud-path-to-your-video-2",
                    "videoMetadata": {
                      "fps": frames-per-second,
                      "duration": duration-in-seconds,
                      "width": frame-width,
                      "height": frame-height,
                      "file_size": file-size-in-bytes,
                      "mime_type": "MIME-file-type-extension"
                    }
                  }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "videos": [
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/og.mp4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/blue_bus_video.mp4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/bluemlisalphutte_flyover.mp4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake_normalized.mp4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/snow_sled.MOV"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/cyclists.MP4"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Video Metadata theme={"dark"}
            {
                "videos": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/video_file.mp4",
                    "videoMetadata": {
                        "fps": 23.98,
                        "duration": 29.09,
                        "width": 1280,
                        "height": 720,
                        "file_size": 5468354,
                        "mime_type": "video/mp4"
                    }
                  }
                ],
                "skip_duplicate_urls": true
              }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Audio files">
          #### [Audio Files](#audio-files)

          The following is an example JSON file for uploading two audio files to Encord.

          <Tip>
            Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
          </Tip>

          * **Template:**  Imports audio files with an Encord title.
          * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "audio": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-custom-audio-file-title.mp3"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Audio Metadata theme={"dark"}
            {
                "audio": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/audio/audio_file.mp3",
                    "audioMetadata": {
                        "duration": 23.98,
                        "file_size": 2900000,
                        "mime_type": "audio/mp3",
                        "sample_rate": 44100,
                        "bit_depth": 24,
                        "codec": "mp3",
                        "num_channels": 2
                    }
                  }
                ],
                "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="PDFs">
          #### [PDFs](#pdfs)

          The following are example JSON files for uploading PDFs to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "pdfs": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-document-02.pdf"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-document-03.pdf",
                  "pdfMetadata": {
                    "fileSize": 300,
                    "numPages": 5
                    }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "pdfs": [
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-01.pdf",

                  },
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-02.pdf",
                    "title": "my-document-02.pdf"
                  },
                  {
                    "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-3.pdf",
                    "title": "my-document-03.pdf",
                    "pdfMetadata": {
                      "fileSize": 300,
                      "numPages": 5
                      }
                  }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Text Files">
          #### [Text Files](#text-files)

          The following are example JSON files for uploading text files to Encord.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "text": [
                {
                  "objectUrl": "<object url_1>"
                },
                {
                  "objectUrl": "<object url_2>",
                  "title": "my-file.html"
                },
                {
                  "objectUrl": "<object url_3>",
                  "title": "my-plain-text-file.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "<object url_4>",
                  "title": "my-csv-file.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "<object url_5>",
                  "title": "my-xml-file.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "<object url_6>",
                  "title": "my-html-file.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
                "text": [
                  {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-file-01.html"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-01.txt",
                  "title": "my-plain-text-file-01.txt"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-02.txt",
                  "title": "my-plain-text-file-02.txt",
                  "textMetadata": {
                    "fileSize": 200,
                    "mime_type": "text/plain"
                  }
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-csv-file-01.csv",
                  "title": "my-csv-file-01.csv",
                  "textMetadata": {
                    "fileSize": 250,
                    "mime_type": "text/csv"
                  }
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-xml-file-01.xml",
                  "title": "my-xml-file-01.xml",
                  "textMetadata": {
                    "fileSize": 300,
                    "mime_type": "application/xml"
                  }
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-html-file-01.html",
                  "title": "my-html-file-01.html",
                  "textMetadata": {
                    "fileSize": 400,
                    "mime_type": "text/html"
                  }
                }
                ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Single images">
          #### [Single Images](#single-images)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          The JSON structure for single images parallels that of videos.

          **Template:** Provides the proper JSON format to import images into Encord.

          **Examples:**

          * **Data** Imports the images only.

          * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "file/path/to/images/file-name-01.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-02.file-extension"
                },
                {
                  "objectUrl": "file/path/to/images/file-name-03.file-extension",
                  "title": "image-title.file-extension"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}
            {
              "images": [
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0003.jpg"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
                },
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/large_images/pexels-ivo-rainha-00057.png"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Image Metadata theme={"dark"}

            {
              "images": [
                {
                  "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my_image.jpg",
                  "imageMetadata": {
                    "mimeType": "image/jpg",
                    "fileSize": 124,
                    "width": 640,
                    "height": 480
                  }
                }
              ],
              "skip_duplicate_urls": true
            }
            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image groups">
          #### [Image groups](#image-groups)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image groups are collections of images that are processed as one annotation task.
          * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
          * Image groups do NOT require 'write' permissions to your cloud storage.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the image groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "image_groups": [
                {
                  "title": "<title 1>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                },
                {
                  "title": "<title 2>",
                  "createVideo": false,
                  "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
                  "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
                  "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
                  "clientMetadata": {"optional": "metadata"}
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image group 01",
                  "createVideo": false,
                  "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg",
                  "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg",
                  "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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 group 02",
                  "createVideo": false,
                  "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0001.jpg",
                  "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0002.jpg",
                  "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0003.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="Image sequences">
          #### [Image sequences](#image-sequences)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Image sequences are collections of images that are processed as one annotation task and represented as a video.
          * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
          * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
          * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
          * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

          <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

          <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

          <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

          **Template:** Provides the proper JSON format to import image groups into Encord.

          **Examples:**

          * **Data:** Imports the images groups only.

          <CodeGroup>
            ```json Template theme={"dark"}
            {
              "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>"
                }
              ],
              "skip_duplicate_urls": true
            }
            ```

            ```json Data theme={"dark"}

            {
              "image_groups": [
                {
                  "title": "Image sequence 001",
                  "createVideo": true,
                  "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/01.jpg",
                  "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/02.jpg",
                  "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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-bucket.obs.eu-de.otc.t-systems.com/images/thing-01.jpg",
                  "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-02.jpg",
                  "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-03.jpg"
                }
              ],
              "skip_duplicate_urls": true
            }

            ```
          </CodeGroup>
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="DICOM">
          #### [DICOM](#dicom)

          For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

          * Each `dicom_series` element can contain one or more DICOM series.
          * Each series requires a title and at least one object URL, as shown in the example below.
          * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

          <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

          The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

          * The first series contains only a single object URL, as it is composed of a single file.
          * The second series contains 3 object URLs, as it is composed of three separate files.
          * The third series contains 2 object URLs, as it is composed of two separate files.

          <Info>
            For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
          </Info>

          ```json JSON for DICOM theme={"dark"}
          {
            "dicom_series": [
              {
                "title": "Series-1",
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series1-file.dcm"
              },
              {
                "title": "Series-2",
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file1.dcm",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file2.dcm",
                "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file3.dcm",
              },
                {
                "title": "Series-3",
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file1.dcm",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file2.dcm",
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title="NIfTI">
          #### [NIfTI](#nifti)

          The following is an example JSON file for uploading two NIfTI files to Encord.

          ```json theme={"dark"}
          {
              "nifti": [
                {
                  "title": "<file-1>",
                  "objectUrl": "https://my-bucket/.../nifti-file1.nii"
                },
                {
                  "title": "<file-2>",
                  "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
                }
              ],
              "skip_duplicate_urls": true
            }

          ```
        </Accordion>
      </AccordionGroup>

      <AccordionGroup>
        <Accordion title=" Multiple file types ">
          You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

          ```json Multiple file types theme={"dark"}

          {
            "images": [
              {
                "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/Image1.png"
              }
            ],
            "videos": [
              {
                "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Cooking.mp4"
              },
              {
                "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Oranges.mp4"
              }
            ],
            "image_groups": [
              {
                "title": "apple-samsung-light",
                "createVideo": true,
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(32).jpg",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(33).jpg",
                "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(34).jpg",
                "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(35).jpg"
              },
              {
                "title": "apple-samsung-dark",
                "createVideo": true,
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(32).jpg",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(33).jpg",
                "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(34).jpg",
                "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(35).jpg"
              }
            ],
            "image_groups": [
              {
                "title": "apple-ios-light",
                "createVideo": false,
                "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(32).jpg",
                "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(33).jpg"
              }
            ],
            "skip_duplicate_urls": true
          }

          ```
        </Accordion>
      </AccordionGroup>
    </Accordion>

    <Accordion title="JSON for AWS Multi-Region Access Point">
      #### Use a Multi-Region Access Point

      When using a Multi-Region Access Point for your AWS S3 buckets the JSON file has to be slightly different from the examples provided. Instead of an object's URL, objects are specified using the ARN of the Multi-Region Access Point followed by the object name. The example below shows how video files from a Multi-Region Access Point would be specified.

      ```json theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
          },
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
            "title": "my-custom-video-title.mp4"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_1.mp4"
          },
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_2.mp4",
            "title": "many-cute-cats.mp4"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </Accordion>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="CSV Format">
    #### Create CSV File for Registration

    In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file.

    Details for each data format are given in the sections below.

    <Info>Encord supports up to 10,000 entries for upload in the CSV file.</Info>

    <Warning>
      * Object URLs can't contain whitespace.
      * For backwards compatibility reasons, a single column CSV is supported. A file with the single `ObjectUrl` column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: "Expected a video, got a file of type XXX".
    </Warning>

    <AccordionGroup>
      <Accordion title="Videos">
        #### Videos

        A CSV file containing videos should contain two columns with the following mandatory column headings:\
        'ObjectURL' and 'Video title'. All headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the video resource.

        * The 'Video title' column containing the `video_title`. If left blank, the original file name is used.

        In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

        | ObjectUrl                           | Video title |
        | ----------------------------------- | ----------- |
        | path/to/storage-location/frame1.mp4 | Video 1     |
        | path/to/storage-location/frame2.mp4 | Video 2     |
        | path/to/storage-location/frame3.mp4 |             |
        | path/to/storage-location/frame4.mp4 | Video 3     |
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Single images">
        A CSV file containing single images should contain two columns with the following mandatory headings:\
        'ObjectURL' and 'Image title'.  All headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the image resource.

        * The 'Image title' column containing the `image_title`. If left blank, the original file name is used.

        In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

        | ObjectUrl                           | Image title |
        | ----------------------------------- | ----------- |
        | path/to/storage-location/frame1.jpg | Image 1     |
        | path/to/storage-location/frame2.jpg | Image 2     |
        | path/to/storage-location/frame3.jpg |             |
        | path/to/storage-location/frame4.jpg | Image 3     |
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Image groups">
        #### Image groups

        A CSV file containing image groups should contain three columns with the following mandatory headings:\
        'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

        * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image group a file will be assigned to.

        In the example below the first two URLs are grouped together into 'Group 1', while the following two files are grouped together into 'Group 2'.

        | ObjectUrl                           | Image group title | Create video |
        | ----------------------------------- | ----------------- | ------------ |
        | path/to/storage-location/frame1.jpg | Group 1           | false        |
        | path/to/storage-location/frame2.jpg | Group 1           | false        |
        | path/to/storage-location/frame3.jpg | Group 2           | false        |
        | path/to/storage-location/frame4.jpg | Group 2           | false        |

        <Note>Image groups do not require 'write' permissions.</Note>
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Image sequences">
        #### Image sequences

        A CSV file containing image sequences should contain three columns with the following mandatory headings: 'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

        * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.

        * The 'Create video' column. This can be left blank, as the default value is 'true'.

        In the example below the first two URLs are grouped together into 'Sequence 1', while the second two files are grouped together into 'Sequence 2'.

        | ObjectUrl                           | Image group title | Create video |
        | ----------------------------------- | ----------------- | ------------ |
        | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
        | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
        | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
        | path/to/storage-location/frame4.jpg | Sequence 2        | true         |

        <Tip>Image groups and image sequences are only distinguished by the presence of the 'Create video' column.</Tip>

        <Note>Image sequences require 'write' permissions against your storage bucket to save the compressed video.</Note>
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="DICOM">
        A CSV file containing DICOM files should contain two columns with the following mandatory headings: 'ObjectURL' and 'Dicom title'. Both headings are case-insensitive.

        * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

        * The 'Series title' column containing the `dicom_title`. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.

        In the example below the first two files are grouped into 'dicom series 1', the next two files are grouped into 'dicom series 2', while the final file will remain separated as 'dicom series 3'.

        | ObjectUrl                           | Series title   |
        | ----------------------------------- | -------------- |
        | path/to/storage-location/frame1.dcm | dicom series 1 |
        | path/to/storage-location/frame2.dcm | dicom series 1 |
        | path/to/storage-location/frame3.dcm | dicom series 2 |
        | path/to/storage-location/frame4.dcm | dicom series 2 |
        | path/to/storage-location/frame5.dcm | dicom series 3 |
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title=" Multiple file types ">
        #### Multiple file types

        You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.

        <Warning>Since the 'Create video' column defaults to `true` all files that **are not** image sequences must contain the value `false`</Warning>

        The example below shows a CSV file for the following:

        * Two image sequences composed of 2 files each.
        * One image group composed of 2 files.
        * One single image.
        * One video.

        | ObjectUrl                           | Image group title | Create video |
        | ----------------------------------- | ----------------- | ------------ |
        | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
        | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
        | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
        | path/to/storage-location/frame4.jpg | Sequence 2        | true         |
        | path/to/storage-location/frame5.jpg | Group 1           | false        |
        | path/to/storage-location/frame6.jpg | Group 1           | false        |
        | ObjectUrl                           | Image title       | Create video |
        | path/to/storage-location/frame1.jpg | Image 1           | false        |
        | ObjectUrl                           | Image title       | Create video |
        | full/storage/path/video.mp4         | Video 1           | false        |
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

***

### Import your data

<AccordionGroup>
  <Accordion title="Import cloud data">
    #### Import Cloud Data

    <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

    1. Navigate to **Data** > **Files & Folders** in the Encord platform.
    2. Click into a Folder.
    3. Click **+ Upload files**.
       A dialog appears.

    <div>
      <img />
    </div>

    4. Click **Import from cloud data**.

    <div>
      <img />
    </div>

    <Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

    6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Import local data">
    #### Import Local Data

    <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

    1. Navigate to **Data** > **Files & Folders** in the Encord platform.
    2. Click into a Folder.
    3. Click **+ Upload files**.
       A dialog appears.

    <img />

    4. Click one of the following:
       * **Upload:** Upload images, videos, and audio files.
         ![Upload dialog](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-001.png)
       * **Batch images as:** Upload image batches as image groups or image sequences.
         ![Batch images as](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-02.png)
       * **DICOM/NifTi:** Upload DICOM or NifTi series.
         ![DICOM/NifTi](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/upload-data-dialog-03.png)

    5. Click **Upload** after selecting your images or series.

       Your files upload into the Folder in Encord.
  </Accordion>
</AccordionGroup>

***

## STEP 2: Curate your Data

### Create a collection

A Collection is a container for data units (images or videos) that you can use to group your data units together.

Creation of a Collection involves [filtering and sorting your data](/platform-documentation/Curate/curation-basics#filters). Once you have selected a smaller group of images, videos or audio files, [create a Collection](/platform-documentation/Curate/curation-basics#collections).

1. Log in to the Encord platform.
   The landing page for the Encord platform appears.

2. Navigate to **Data** > **Explore**.
   The *All folders* page appears with a list of all folders in Encord.

3. Open a folder.

4. Click the **Explorer** button.
   The *Index Explorer* page appears.

   ![Access Index Explorer](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-access-index.gif)

5. Search, sort, and filter your data until you have the subset of the data you need.

   ![Sort and Filter](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/sort-and-filter.gif)

6. Select one or more of the images/frames/audio files in the Explorer workspace.
   A ribbon appears at the top of the Explorer workspace.

   <Note>Selecting a video frame selects the entire video. Specific frames from a video cannot be selected.</Note>

   ![Create Collection in Index](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-create-collection.gif)

7. Click **Select all** to select all the files in the subset.

   <Note>Use <kbd>Command + A</kbd> as a short cut to select all files.</Note>

8. Click **Add to a Collection**.

9. Click **New Collection**.

10. Specify a meaningful title and description for the Collection.

    <Note> The title specified here is applied as a tag/label to every selected image.</Note>

11. Click **Collections** to verify the Collection appears in the Collections list.

## Collection actions menu

Each collection in the Explorer filter panel has a **...** (horizontal dots) button that opens a collection actions submenu. The submenu provides quick access to all available actions for that collection.

The submenu displays:

* The **collection name** in bold at the top of the menu.
* The **collection ID** beneath the name. Click the copy icon next to the ID to copy it to your clipboard.
* **Actions grouped into sections** separated by dividers, making it easier to find the right action. Actions are organized into the following groups:
  * **Navigate** — for example, View in Explorer.
  * **Manage** — for example, Edit Details.
  * **Data** — for example, Add to Dataset and Download CSV.
  * **Workflow** — for example, Task Actions, Bulk Classify, Convert Collection, and Edit Object Class. These actions appear only when you are working within a project.
  * **Danger** — for example, Delete.

<Note>Sections with no available actions for your current context are hidden automatically — no empty dividers appear.</Note>

<Note>The grouped layout and copyable collection ID apply only to the collection actions submenu in the Explorer filter panel. The collections table row menu is unchanged.</Note>

***

## STEP 3: Set Up Your Project

### Create a Dataset from a Collection

Once you have a Collection, you can create a Dataset from your Collection.

***

### Create an Ontology

An Ontology is a structured framework that defines the categories, labels, and relationships used to annotate data consistently and accurately. Ontologies define what you want labeled.

<Note>We recommend learning about [Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) in Encord before creating Ontologies. </Note>

1. Click the **New ontology** button in the *Ontologies* section to create a new Ontology.

<div>
  <img />
</div>

2. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.

3. Click **Next** to continue.

<div>
  <img />
</div>

4. Define your Ontology structure. See our [documentation on Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) for more information on the various types of objects, classifications, and attributes.

**To add objects:**

<Warning>Ensure that you add *Audio Region* objects for audio files and *Text Region* objects for text files.</Warning>

<div>
  <img />
</div>

1. Click the **Add object** button.

2. Do one of the following:

   * Select a **Shared class**
   * Click **New Object**

   <Note>
     **Shared classes** cannot be edited while creating an Ontology. To edit a shared class go to the **Ontologies** > **Shared classes** page.
   </Note>

3. To create a new object, give the object a name. For example "Apple".

4. Select a shape for the object. For example *polygon*.

5. Optionally, enable the **Required** toggle to mark the object as *Required*.

6. Optionally, add attributes to the object.

7. Repeat these steps for as many objects as necessary.

**To add attributes to an object**:

You can add attributes to objects that define the object's characteristics. For example the object "Apple" can have an attribute "Color".

<div>
  <img />
</div>

1. Click the arrow icon next to an object to add attributes to the object.

2. Give the attribute a name. For example "Color".

3. Click the attribute type to change the attribute type. The default attribute type is a text field.

4. Click **Add option** to add an option, if you have chosen a radio button or checklist attribute.

5. Enter a name for the attribute option. For example, the attribute "Color" can have the options "Red", "Green", and "Yellow".

6. Click the **Back to parent** button to return the Ontology creation view.

**To add a classification**:

<div>
  <img />
</div>

1. Click **Add classification**.

2. Do one of the following:

   * Select a **Shared class**
   * Click **New classification**

   <Note>
     **Shared classes** cannot be edited while creating an Ontology. To edit a shared class go to the **Ontologies** > **Shared classes** page.
   </Note>

3. For a new classification, give the classification a name. For example, "Time of day".

4. Optionally, configure the classification. The default classification type is a text field.

5. Optionally, enable the **Required** toggle to mark the object as *Required*.

6. Repeat these steps for as many classifications as necessary.

**Configure classifications**:

You can configure classifications to change the classification type, and to add classification options to radio buttons and check lists.

<div>
  <img />
</div>

1. Click the arrow icon next to an object to configure the classification.

<div>
  <img />
</div>

2. Click the classification type to change the classification type. The default classification type is a text field.
3. Click **Add option** to add an option if you have selected a radio button or check list classification.
4. Enter a name for the classification option. For example, the classification "Time of day" can have the options "Night" and "Day".
5. Click the **Back to parent** button to return the Ontology creation view.

***

### Create a Custom Agent

Agents enable you to set up custom actions like pre-labeling, leveraging foundation models such as GPT-4, automated quality assurance, or other tailored actions to suit your Workflow.

Use the Encord SDK to configure your Advanced Custom Agent. The Agent executes the configured SDK script for all tasks that are routed through the Agent stage in your Workflow.

<AccordionGroup>
  <Accordion title="General Example">
    The General Example script shows how to configure a Workflow Agent with the name `Agent 1` and with a pathway called `continue to Review`.

    <Tip>Agent nodes can be used in conjunction with bundles to [efficiently handle bulk actions](/sdk-documentation/general-sdk/sdk-bulk-action-best-practices)</Tip>

    Ensure that you:

    * Replace `<private_key_path>` with the path to your private key.
    * Replace `<project_hash>` with the hash of your Project.
    * Insert your custom logic where the comment instructs you to do so.

    ```python General Example theme={"dark"}
    # Import dependencies
    from encord.user_client import EncordUserClient
    from encord.workflow import AgentStage

    # 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 that contains the agent. Replace <project_hash> with the hash of your Project
    project = user_client.get_project(<project_hash>)

    # Specify the Agent
    agent_stage = project.workflow.get_stage(name="Agent 1", type_=AgentStage)
    for task in agent_stage.get_tasks():

        # Now you have the agent task containing the data hash
        # Insert you custom logic here

    # When the custom logic is completed, the task can be moved forward to the selected pathway
    task.proceed(pathway_name="continue to Review")
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Pre-Classification of Images Using GPT 4o">
    ```mermaid theme={"dark"}
     sequenceDiagram
     participant AWS as AWS (Image Storage)
     participant Encord as Encord (Project)
     participant Agent as Agent Node (In Encord)
     participant Server as Your Server
     participant OpenAI as OpenAI

     AWS->>Encord: Send Signed Image URLs
     Encord->>Agent: Add Signed Image URL to Agent node
     Agent->>Server: Send Signed Image URL
     Server->>OpenAI: Send Image Data + Prompt
     OpenAI-->>Server: Return Classification
     Server->>Server: Transform Classification to Encord label structure
     Server->>Agent: Save Labels to Encord
     Agent->>Encord: Classification Saved to Label Row
     Encord->>Encord: Task Moved to Annotation Stage
    ```

    <Note> See our [end-to-end guide](/agents-documentation/Task-Agents/GPT4PreClassificationImages) for Pre-Classification using GPT 4o for more detailed information.</Note>

    The Pre-Classification script uses GPT 4o mini to route images to different annotation stages depending on what it is contained in the image. The Pre-Classification script applies to the following Workflow.

    <div>
      <img />
    </div>

    <Tip>Agent nodes can be used in conjunction with bundles to [efficiently handle bulk actions](/sdk-documentation/general-sdk/sdk-bulk-action-best-practices)</Tip>

    In the following script:

    * Replace `<private_key_path>` with the hash of your private key.
    * Replace `<project_hash>` with the hash of your Project.
    * Replace `Agent 1` with the name of your Agent stage.

    <CodeGroup>
      ```python Pre-Classification for Images Example theme={"dark"}
      # Import dependencies
      from encord.user_client import EncordUserClient
      from encord.workflow import AgentStage
      import openai
      import base64
      import requests
      import json

      # Initialize your OpenAI client
      openai.api_key = "<your_openai_api_key>"

      def get_classification_from_the_model(media_content):
          """
          Example function that passes media to OpenAI's ChatGPT API along with the prompt
          and parses the result.
          """
          prompt = """
          You are an image analysis expert. You're working on a project that includes annotation of different pets images.
          Your task is to assign one of the following tags to the image: "cat", "dog", "other".

          Reply in JSON format of the following structure: { "classification": cat|dog|other }
          """

          completion = openai.ChatCompletion.create(
              model="gpt-4o-mini",
              messages=[
                  ChatCompletionSystemMessageParam(role="system", content=prompt),
                  ChatCompletionUserMessageParam(
                      role="user",
                      content=[
                          ChatCompletionContentPartImageParam(
                              image_url=ImageURL(url=f"data:image/jpeg;base64,{media_content}", detail="auto"),
                              type="image_url",
                          )
                      ]
                  ),
              ],
              response_format=ResponseFormat(type="json_object"),
              max_tokens=1000,
          )

          raw_text_completion = completion.choices[0].message.content
          try:
              parsed_result = json.loads(raw_text_completion)
              return parsed_result["classification"].lower()
          except Exception as e:
              print(f"Failed to process the model response: {e}")
              return None


      # 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 that contains the agent. Replace <project_hash> with the hash of your Project
      project = user_client.get_project("<project_hash>")

      radio_classification = project.ontology_structure.get_child_by_title(
      title="Animal",
      type_=Classification,
      )

      cat_option = radio_ontology_classification.get_child_by_title(
      title="Cat", type_=Option
      )

      dog_option = radio_ontology_classification.get_child_by_title(
      title="Dog", type_=Option
      )

      # Specify the Agent
      agent_stage = project.workflow.get_stage(name="Agent 1", type_=AgentStage)

      for task in agent_stage.get_tasks():
          # Got a task for the following data unit
          print(f"{task.data_hash} -> {task.data_title}")

          # Getting a label row for the data unit
          label_row = project.list_label_rows_v2(data_hashes=[task.data_hash])[0]
          label_row.initialise_labels(include_signed_url=True)

          # Downloading the media:
          media_response = requests.get(label_row.data_link)
          media_content = base64.b64encode(media_response.content).decode("utf-8")

          # Now we can send the media to OpenAI:
          model_response = get_classification_from_the_model(media_content)

          # And interpret the result:
          match model_response:
              case "cat":

                  # Create a classification instance
                  classification_instance = (
                      radio_ontology_classification.create_instance()
                  )

                  radio_classification_instance.set_answer(
                      answer=cat_option
                  )
                  
                  label_row.add_classification_instance(radio_classification_instance)
                  label_row.save()

                  task.proceed(pathway_name="Cat")
              case "dog":

                  # Create & save classification instance
                  classification_instance = (
                      radio_ontology_classification.create_instance()
                  )
              
                  radio_classification_instance.set_answer(
                      answer=dog_option
                  )

                  
                  label_row.add_classification_instance(radio_classification_instance)
                  label_row.save()

                  task.proceed(pathway_name="Dog")
              case _:
                  task.proceed(pathway_name="Other")
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Pre-Labeling Videos Using a Mock Model">
    <Warning>
      This guide makes the following assumptions:

      * You have a model that takes video frames as an input and provides bounding box coordinates and confidence scores as an output.
      * You have installed the `encord-agents` library using the following command:

      ```
      python -m pip install encord-agents
      ```
    </Warning>

    The Pre-Labeling Script selects a random class from the Ontology, generates random bounding box labels, and applies random confidence scores for video frames before advancing the videos to the annotation stage (`Annotate 1`). Below is an example of a Workflow where the Pre-Labeling agent can be effectively utilized.

    <div>
      <img />
    </div>

    <Warning>
      To authenticate, you must set either of following environment variables in the environment that you plan to run your agents.

      * ENCORD\_SSH\_KEY: Containing the raw private key file content
      * ENCORD\_SSH\_KEY\_FILE: Containing the absolute path to the private key file
    </Warning>

    In the following script:

    * Replace `<project_hash>` with the hash of your Project.
    * Replace the mock model with your own model, and adapt the rest of the script according to your needs.
    * If you choose to give your python file a different name, ensure you replace all references to `prelabel_video.py` with your new file name.

    ```python prelabel_video.py theme={"dark"}
    #Import Dependencies
    import random
    from dataclasses import dataclass
    from typing import Iterable

    import numpy as np
    from encord.objects.coordinates import BoundingBoxCoordinates
    from encord.objects.ontology_labels_impl import LabelRowV2
    from encord.project import Project
    from encord_agents.core.data_model import Frame
    from encord_agents.tasks import Depends, Runner
    from encord_agents.tasks.dependencies import dep_video_iterator
    from numpy.typing import NDArray
    from typing_extensions import Annotated


    # Set the Environment variable to authenticate with Encord
    ENCORD_SSH_KEY_FILE="/path/to/file/" prelabel_video.py

    runner = Runner(project_hash="<project_hash>")

    # === BEGIN MOCK MODEL === #
    @dataclass
    class ModelPrediction:
        label: int
        coords: BoundingBoxCoordinates
        conf: float


    def fake_predict(image: NDArray[np.uint8]) -> list[ModelPrediction]:
        return [
            ModelPrediction(
                label=random.choice(range(3)),
                coords=BoundingBoxCoordinates(
                    top_left_x=random.random() * 0.5,
                    top_left_y=random.random() * 0.5,
                    width=random.random() * 0.5,
                    height=random.random() * 0.5,
                ),
                conf=random.random() + 0.5,
            )
            for _ in range(10)
        ]


    model = fake_predict
    # === END MOCK MODEL === #

    @runner.stage(stage="Pre-Labeling Agent")
    def run_something(
        lr: LabelRowV2,
        project: Project,
        frames: Annotated[Iterable[Frame], Depends(dep_video_iterator)],
    ) -> str:
        ontology = project.ontology_structure

        # Create an object instance for each frame in the video and save the labels. 
        for frame in frames:
            outputs = model(frame.content)
            for output in outputs:
                ins = ontology.objects[output.label].create_instance()
                ins.set_for_frames(
                    frames=frame.frame, coordinates=output.coords, confidence=output.conf
                )

                lr.add_object_instance(ins)

        lr.save()

        # Return the name of the stage the task should progress to
        return "Annotate 1"  


    if __name__ == "__main__":
        runner.run()
    ```
  </Accordion>
</AccordionGroup>

## Repeatable Ontology Feature Requirements

Some agent templates support **repeatable** Ontology feature requirements, which allow you to assign multiple ontology features to a single role. This is useful for agents that need to operate across several classes simultaneously, for example, a merge-object-classes agent that combines multiple source classes into one.

### Selecting features for a repeatable requirement

When an agent template declares a requirement as repeatable, the configuration form displays a **multi-select tree picker** instead of the standard single-select picker.

<Note>The multi-select tree picker only appears for requirements that the agent template has marked as repeatable. Requirements that are not repeatable continue to use the standard single-select behavior.</Note>

* Select as many Ontology features as the requirement allows by clicking each feature in the tree picker.
* The form enforces a **minimum** number of selections. You cannot submit the form until you have selected at least the required number of features. If you select too few, the form displays the message: *"Please select at least N features"*.
* If the template defines a **maximum** number of selections, the picker prevents you from selecting additional features once the maximum is reached.

### How selected features appear in the agent detail view

After you save the agent, the detail view groups all features selected for a repeatable requirement under a single label. For example, if you selected **ClassA** and **ClassB** for a role called **Source Object Classes**, the detail view displays:

**Source Object Classes:** `ClassA` `ClassB`

### Ontology compatibility and repeatable requirements

When you select an ontology during agent creation, Encord automatically filters out ontologies that do not contain enough eligible features to satisfy the minimum selection count for any repeatable requirement. Only ontologies with a sufficient number of matching features appear in the Ontology selector.

***

### Create a Workflow template

*Workflows* allow you to design and manage the flow of tasks through various stages of a Project. You have control over how tasks progress and how different stages interact.

<AccordionGroup>
  <Accordion title="Video tutorial - Creating workflow templates">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

To set up a Workflow template, navigate to the Project section of the Encord platform and select the **Templates** tab.

<div>
  <img />
</div>

**1. Add users to the Workflow**:

Add users from your [Workspace](/platform-documentation/General/general-workspace-settings) to the Workflow by clicking **Invite collaborators**.

<div>
  <img />
</div>

* Collaborators are added based on their role within the project - select the role you would like the collaborator(s) to have.
* Start typing the email of a user you would like to add into the area highlighted on the image below, and select the user from the list that appears. Repeat this for every user that will have the same role.
* When you are done selecting users for this role, click **Add**.

<div>
  <img />
</div>

<Note>Learn more about managing collaborators in the [Managing collaborators](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#managing-collaborators) section.</Note>

**2. Configure your Workflow**:

The canvas is populated with a simple Workflow by default.

Click the **Add stage** button to show all Workflow components.

<div>
  <img />
</div>

Customize your Workflow by pulling components onto the canvas.

<div>
  <img />
</div>

Add the stages and other components you require for your Workflow onto the canvas:

* All workflows must begin with the [**Start**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#start) stage.

* All workflows must contain an [**Annotate**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate) stage.

* Add [routers](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#routers) to your Project to determine different pathways through your Workflow a task can take.

* Add as many [**Review**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#review) stages as necessary.

* All workflows must end at a [**Complete**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#complete) stage.

* Link all components on the canvas by clicking and dragging from one connection point to another.

<div>
  <img />
</div>

All Workflows can be saved as a [template](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates) by clicking the **Save as a new template** button.

<div>
  <img />
</div>

**3. Configure the stages of your Workflow**:

After you arranged the stages in the composer, it is time to configure the details of each stage.

* Click an **Annotate** card on the canvas to start editing the [annotation stage](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate).
  * Give the stage a descriptive name.
  * Add annotators. If you'd like to specify annotators for this stage, add them as collaborators. For full details on how collaborators can work on tasks at each stage, see our section on [managing collaborators](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#managing-collaborators).
  * Optionally, add a [Webhook](/platform-documentation/Annotate/annotate-webhooks-notifications) to receive notifications when labels are submitted at this stage.

<Note>More details about configuring annotation stages can be found in the [**Annotate** section](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate) below</Note>

* Click a **Review** card on the canvas to start editing the [review stage](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#review).
  * Give the stage a descriptive name.
  * Add reviewers. If you want to specify reviewers for this stage, add them as collaborators. For full details on how collaborators can work on tasks at each stage, see our section on [managing collaborators](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#managing-collaborators).

<Note>More details about configuring review stages can be found in the [**Review** section](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#review) below.</Note>

* Click a **Router** card on your canvas. See the [router section](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#routers) for more details on how different types of routers can be configured.

* Optionally, add a Webhook to the **Complete** stage to receive a notification when a task has been completed.

* Optionally, add [*User assignment restrictions*](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#user-assignment-restriction) if users in this node should be prevented from being assigned to tasks they completed in the nodes listed.

<Note>More details on routers can be found in the [router section](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#routers) below.</Note>

### Create the Project

Projects in Encord bring together Datasets, Ontologies, and Workflows. Datasets are labeled according to the Ontology, while the Workflow defines how tasks progress through the Project from start to finish.

<Note>
  Projects only require a **Title** to be saved.
</Note>

<iframe title="YouTube video player" />

1. Select **Projects** in the Encord platform.

2. Click the **+ New annotation project** button or use <kbd>CONTROL</kbd> / <kbd>CMD</kbd>  + <kbd>ENTER</kbd> to create a new Project.

3. Give the Project a meaningful title and description.

<Note>
  If you are part of an [Workspace](/platform-documentation/General/general-workspace-settings), an optional [Project tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags) drop-down is visible. Project tags are useful for categorizing and finding your Projects. Select as many tags as are relevant for your Project.
</Note>

4. Apply any meaningful [**Project tags**](/platform-documentation/General/general-workspace-settings#project-tags) you need to the Project.

5. Specify the Workflow you want to use for the Project.

6. Click the **Templates** > **Load from template** to use a [Workflow template](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates).

7. Select the template you want to use and click **Load template**.

8. Click the **Ontology** button.

9. Select an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) from the list, or [create a new Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies) by clicking the **New ontology** button.

10. Click the **Data** button.

11. Select one or more data sources from the list.

12. Click **Collaborators**.

13. Specify the users and the roles they have in the Project.

14. Click **Create project** to finish creating the Project.

#### Add users to the Project

After creating a Project, invite users to act as annotators, reviewers, team managers, and admins. Collaborators can be added as individuals, or as part of [user groups](/platform-documentation/General/general-workspace-settings#user-groups).

<AccordionGroup>
  <Accordion title="Invite individuals">
    1. Navigate to **Projects** in the Encord app.

    <div>
      <img />
    </div>

    2. Select the Project you want to add users to.

    3. Navigate to the *Settings* tab.

    4. Navigate to the *Team* pane.

    5. Click **Invite collaborators**.

    <div>
      <img />
    </div>

    6. Select the desired role for the users.

    7. Enter the users' email addresses and choose the users to assign the selected role.

    8. Click **Add** to include the selected users in the Project.

    <div>
      <img />
    </div>

    9. Repeat this process for each required user role.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Invite user groups">
    <Info>To invite [user groups](/platform-documentation/General/general-workspace-settings#user-groups) your Workspace must have user groups.</Info>

    1. Navigate to **Projects** in the Encord app.

    <div>
      <img />
    </div>

    2. Select the Project you want to add users to.

    3. Navigate to the *Settings* tab.

    4. Navigate to the *Team* pane.

    5. Select the *Groups* tab.

    6. Click **Manage**.

    <div>
      <img />
    </div>

    7. Select a group from the dropdown.

    8. Select the role you want the user group to have.

    9. Click **Add** to add the user group to the Project.

    <div>
      <img />
    </div>

    10. Repeat this process for each required user group and role.
  </Accordion>
</AccordionGroup>

## STEP 4: Label your Data

Now you are ready to label your data. We recommend you and your team watch these introductory videos.

<Tip>For more details, see our comprehensive [tutorial on labeling here](/platform-documentation/GettingStarted/gettingstarted-labeling).</Tip>

<AccordionGroup>
  <Accordion title="Video tutorial - Introduction to image annotation">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Video tutorial - Introduction to video annotation">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

## STEP 5: Export your Labels

<Info>Only Project admins can export labels</Info>

<Tip>Descriptions of all information contained in the export file can be found [in the export file reference](/platform-documentation/Annotate/annotate-export/annotate-export-json).</Tip>

<iframe title="YouTube video player" />

<Tip>
  To export labels for specific tasks:

  1. Select the tasks
  2. Click **Bulk actions**
  3. Select **Export**
</Tip>

1. Click **Export** while in a Project.

   The *Export labels* dialog appears.

2. Specify the following:
   * **Format:** Specify the format to export the labels (JSON or COCO).
   * **Stage:** Specify the Workflow stage to export the labels from.
   * **Generate signed URLs:** Specify whether to generate signed URLs for the data units that have labels.
   <Note>
     Enabling this option can significantly increase export times.
   </Note>
   * **Save as new version:** Specify to version the labels.
     * Provide a meaningful name for the label version.
   * **Labels to include:** Specify the labels to include. You can export all labels or select specific object or classification labels to export.

3. Click **Export**.

   A *Labels export in progress* toast message appears.


# User and Resource Management
Source: https://docs.encord.com/end-to-end/GettingStartedE2E/user-management



<Warning>
  All steps in this guide must be performed by Workspace Admins.
</Warning>

## Part 1: User Management

### Invite Users to your Workspace

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click the **+ Invite users** button.
   A dialog appears

<div>
  <img />
</div>

3. Type the email addresses of the users you want to invite.
4. Press <kbd>ENTER</kbd>.
5. Select the role you want the users to have.
6. Click **Add** to invite the users to your Workspace.

<Note>
  Users accept invitations by clicking the email link. The link redirects users to the Encord login page, regardless of whether the user has an existing Encord account.
</Note>

<div>
  <img />
</div>

### Remove Users and Revoke Invitations

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Search for the user you want to remove from your Workspace.

3. Click **User details**

<div>
  <img />
</div>

4. Click **Remove user**.
   If the user being removed is the sole Admin for any Projects or Datasets within the Workspace, you are prompted to select a replacement user from within your Workspace.

<div>
  <img />
</div>

<Note>Admins cannot be removed from a Workspace. To remove an Admin from your Workspace, contact [support@encord.com](mailto:support@encord.com).</Note>

### Invite Status

The user's status shows the status of the invitation to your Workspace. Users can have the following status:

* **Invited**: Shows the date the user was invited to your Workspace. The invitation is pending.
* **Declined**: Shows the date the user declined the invitation to join your Workspace.
* **Joined**: Shows the date the user joined your Workspace.

### Change User roles

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Search for the user you want to change the user role for.

3. Click the user role dropdown of the user.

4. Select the role you want the user to have.

<div>
  <img />
</div>

**To change a user's role for a resource**:

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click **User details** in the **Action** column for the user.

3. Click the user's current role in the Role column, then select the new role you want to assign for the resource.

<Tip>
  Click **Change role** from the **Bulk actions** dropdown to change a user's role in multiple Projects at once.

  <div>
    <img />
  </div>
</Tip>

## Part 2: User Assignment

<Note>
  The ability to add users to the following resources is coming soon.

  * Datasets
  * Ontologies
  * Cloud Integrations
  * Workflow templates
  * Folders
</Note>

### Assign One User to Multiple Projects

Users can be assigned to various resources even before the users accepts their invitation to join your Workspace.

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click **User details** in the **Action** column for the user you want to assign.

3. Select the resource you want to assign a user to by clicking the relevant tab.

4. Click the **Assign to** button. Different resources have different resource names on the button.

5. Select all the resources you want to assign the user to from the list. Use the search bar to search for a specific resource if necessary.

6. Click **Select a role**.

7. Select a role for the user. The role is assigned for all selected resources.

8. Click **Assign to annotation projects** to assign the user to your selected Projects.

**To remove users from resources**:

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click **User details** in the **Action** column for the user you want to remove.

3. Select the resource you want to remove the user from by clicking the relevant tab.

4. Click the red icon in the **Remove** column of the resource you want to remove the user from.

<Tip>
  Select **Remove user** from the **Bulk actions** dropdown to remove users from multiple Projects at once.

  <div>
    <img />
  </div>
</Tip>

### Assign Multiple Users to One Project

To manage Project collaborators, select the *Team* pane in your project *Settings*. Collaborators can be added individually or as [groups of users](/platform-documentation/General/general-workspace-settings#user-groups).

**To add collaborators to a Project**:

1. Search for the collaborator or the [group](/platform-documentation/General/general-workspace-settings#user-groups) you want to add. Multiple collaborators and groups can be added at once.

<Note>
  You can invite users who are not part of your Workspace. Invitations to join the Workspace are sent to them, and once accepted, they become Project collaborators. See instructions on how to do this [here](/platform-documentation/General/general-workspace-settings#accepting-invites).
</Note>

<Info>
  Only group members are added when a group is assigned to a Project. Group managers are not included.
</Info>

<div>
  <img />
</div>

2. Select a user role.
   * **Annotator**: Can access and label tasks in all or selected Annotate stages in the Project.
   * **Reviewer**: Can access and review tasks in all or selected Review stages in the Project.
   * **Annotator & Reviewer**: Performs both annotation and review tasks.
   * **Team Manager**: Can access and label tasks in all stages in the Project. Can move, assigns, prioritize tasks to users. Can manage Project collaborators.
   * **Admin**: Grants full administrative control over the Project.

3. Click **Add to project**.

<Info>
  To remove a user or group from the Project click the *Delete* icon in the *Unassign* column.

  <div>
    <img />
  </div>
</Info>

<AccordionGroup>
  <Accordion title="How to import collaborators using a CSV">
    1. Click **Actions**.
    2. Select **Import collaborators**.
    3. Add the CSV file containing users and their roles.
    4. Click **Submit**.

    <div>
      <img />
    </div>

    CSV files must be formatted in the following manner:

    ```csv theme={"dark"}
    Email,Role,Group
    david@acme.com,Admin,
    adam@acme.com,Annotator,
    joe@acme.com,Annotator,
    ```
  </Accordion>
</AccordionGroup>

### Change User Access

A user's access to various resources can easily be modified.

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click **User details** in the **Action** column for the user.

3. Click the user's current role in the Role column, then select the new role you want to assign for the resource.

<Tip>
  Click **Change role** from the **Bulk actions** dropdown to change a user's role in multiple Projects at once.

  <div>
    <img />
  </div>
</Tip>


# Managing External Workforces
Source: https://docs.encord.com/end-to-end/GettingStartedE2E/workforce-managers



The Workforce Manager user role is designed so your 3rd-party workforces can self-organize without the need for admin involvement. This feature allows Workforce Managers to view all users in a Workspace.

<Note>
  You can prevent multiple different Workforce Managers from seeing other users in a Workspace. The Workforce Managers can be restricted to seeing only members of their 3rd party workforce members. Contact us at [support@encord.com](mailto:support@encord.com) if you want to restrict who Workforce Managers see in Workspaces.
</Note>

<Warning>
  This guide assumes you have already added data into Encord and set up your annotation Projects.
</Warning>

## TL;DR

**Key Features and Usage:**

* **Upgrade to Workforce Manager:** Workspace Admins can add members with the **Workforce Manager** role to the [Workspace](/platform-documentation/General/general-workspace-settings#user-roles).
* **Workspace Visibility:** Workforce Managers can view all users in a Workspace.
* **Group Creation:** Workforce Managers can create user groups.
* **Group Membership Management:** Within a group, Workforce Managers can:
  * Add and remove any Workspace member.
  * Add other Workforce Managers or Admins as administrators or viewers of the group.
* **Project Group Assignment:** When added to a Project as a Workforce Manager, you can add groups you manage (or are an admin of) to that Project.
* **Centralized User Management:**
  * When a group is added to a Project only group members are added. Group Managers are not.
  * Once a group is added to a Project, the Workforce Manager can on/off-board users from the group. These changes automatically apply to all Projects where that group has been added.

**Benefits:**

* Simplifies user management for workforce members involved in multiple Projects.
* Allows designated Workforce Managers to control team membership across Projects in one central location.
* Efficiently on/off-board users (for example: when a member joins or leaves the workforce), automatically updating their Project access by removing them from the group.

## STEP 1: \[Workspace Admin] Add Workforce Managers to Your Workspace and Project

<Note>
  Repeat this step for each Workforce Manager.
</Note>

**To add Workforce Managers, as a Workspace admin:**

1. Click **Settings** in the **My workspace** section.
   The *Users* page appears.

2. Click the **+ Add user** button.
   A dialog appears.

3. Type the email addresses of the users you want to add.

4. Select the *Workforce manager* role.

5. Click **Add** to add the users to your Workspace.

<div>
  <img />
</div>

6. Find the user you added in the list of Users.

7. Click the *Ellipsis* icon.

8. Click the dropdown

9. Select the *Workforce Manager* role.

<div>
  <img />
</div>

The Workforce Manager must be added to all Projects they are expected to manage.

<Tip>
  Alternatively, Workforce Managers can create Projects themselves if you prefer.
</Tip>

10. Navigate to the Project you want the Workforce Manager to manage.

11. Navigate to the **Settings** tab.

12. Navigate to **Team**.

13. Click **+ Invite collaborators**.

14. Type the Workforce Manager's email address.

15. Select the *Team Manager* user role.

16. Click **Add**.

Repeat this for as many Projects as necessary.

<div>
  <img />
</div>

## STEP 2: \[Workspace Admin] Add Workforce Members to Your Workspace

<Note>
  Repeat this step for each Workforce member.
</Note>

To add Workforce members, as a Workspace admin:

1. Click **Settings** in the **My workspace** section.
   The *Users* page appears.

2. Click the **+ Add user** button.
   A dialog appears.

3. Type the email addresses of the users you want to add.

4. Select the *Workforce* role.

5. Click **Add** to add the users to your Workspace.

<div>
  <img />
</div>

## STEP 3: \[Workforce Manager] Add Workforce to User Groups

The Workforce Manager can add their workforce to user groups, such as 'Annotators' and 'Reviewers'. Users added to groups by the Workforce Manager **are not** added to the Workspace but can be added to Projects, Datasets, and Ontologies.

<Tip>
  When creating groups, keep in mind that all members of a user group are assigned the same role when added to a Project.
</Tip>

1. Click **Settings** in the **My workspace** section.
   The *Users* page appears.

2. Click the **Groups** tab.
   The Groups section appears.

3. Click the **+ Create group** button.
   A dialog appears.

4. Give the group a meaningful name, for example 'Annotators'.

5. Type the email addresses of all workforce members.

6. Click **Add**.

<div>
  <img />
</div>

7. Click **Next**

8. Type your own email address to add yourself as the group's manager.

<div>
  <img />
</div>

9. Click **Add**.

10. Click **Create group**.

Repeat this step for as many groups as necessary.

## STEP 4: \[Workforce Manager] Add Groups to Project

<Note>
  This step should be done by the Project Admin
</Note>

The Workforce Manager must be added to all Projects they are expected to manage.

<Tip>
  Alternatively the Workforce Manager can create the Project themselves if you prefer
</Tip>

1. Navigate to the Project you want the Workforce Manager to manage.

2. Navigate to the **Settings** tab.

3. Navigate to **Team**.

4. Click **+ Invite collaborators**.

5. Type the Workforce Manager's email address.

6. Select the *Team Manager* user role.

7. Click **Add**.

Repeat this Step for as many Projects as necessary.

<div>
  <img />
</div>


# Curating and Annotating Audio Files
Source: https://docs.encord.com/end-to-end/Modalities/audio/audio-curation-label



<Warning>
  This guide assumes your audio files are stored in AWS. To learn how to create integrations with other cloud providers [click here](/platform-documentation/General/annotate-data-integrations).
</Warning>

## STEP 1: Import your Audio Files

<Steps>
  <Step title="Set Up AWS">
    Before you can do anything with the Encord platform and cloud storage, you need to configure your cloud storage to work with Encord. Once the integration between Encord and your cloud storage is complete, you can then use your data in Encord.

    In order to integrate with AWS S3, you need to:

    1. Create a permission policy for your resources that allows appropriate access to Encord.
    2. Create a role for Encord and attach the policy so that Encord can access those resources.
    3. Activate Cross-origin resource sharing which allows Encord to access those resources from a web browser.
    4. Test the integration to make sure it works.

    <Tip>See our [AWS integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration) for a detailed explanation of setting up AWS to work with Encord.</Tip>

    You have the following options to integrate AWS and Encord:

    <div lang="en">
      <head>
        <meta />

        <meta name="viewport" />

        <title>Clickable Div</title>
      </head>

      <div>
        <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration">
          Use AWS UI
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration#terraforming-your-aws-s3-integration">
          Use Terraform
        </a>
      </div>
    </div>
  </Step>

  <Step title="Create AWS Integration in Encord">
    <Note>Create an S3 bucket to store your files if you haven't already. Your S3 bucket permissions should be set to be blocking all public access.</Note>

    In the *Integrations* section of the Encord platform, click **+New integration** to create a new integration.

    <div>
      <img />
    </div>

    Select *AWS S3* at the top of the chooser.

    <div>
      <img />
    </div>

    <Note>It is essential you do not close this tab or window until you have finished the whole integration process. If you use the AWS UI for integration, we advise opening the AWS console in a separate tab.</Note>

    <Tip>See our [AWS integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration) for a detailed explanation of how to set up the AWS integration.</Tip>
  </Step>

  <Step title="Create JSON file for Registration">
    <Tip> See our documentation [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) for more comprehensive information</Tip>

    Create a JSON file based on the templates provided below. `audioMetadata` is optional unless you are using a [client-only access integration](/platform-documentation/General/annotate-data-integrations#strict-client-only-access).

    The `title` field is optional. If omitted, the audio file path and name are used as the default title. For example, if the file is located at `https://encord-solutions-bucket.s3.eu-west-2.amazonaws.com/path/to/my/bucket/song2.mp3`, the title defaults to `/path/to/my/bucket/song2.mp3`.

    | Key or Flag      | Required? | Default value           |
    | ---------------- | --------- | ----------------------- |
    | "objectUrl"      | Yes       |                         |
    | "title"          | No        | The file's path + title |
    | "audioMetadata"  | No        |                         |
    | "clientMetadata" | No        |                         |
    | "createVideo"    | No        | false                   |

    <Note> `audioMetadata` must be specified when a [Strict client-only access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access) integration is used. In all other cases, `audioMetadata` is optional, but including it significantly reduces import times.</Note>

    <Warning>
      When the `audioMetadata`, `imageMetadata`, or `videoMetadata` flags are present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. **It is crucial that the metadata you provide is accurate**.
    </Warning>

    <Note>Keys / Flags that are not required can be omitted from the JSON file entirely.</Note>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
      "audio": [
          {
          "objectUrl": "/path/to/my/bucket/song.mp3",
          "audioMetadata": {
              "duration": 180.98,
              "file_size": 2900000,
              "mime_type": "audio/mpeg",
              "sample_rate": 44100,
              "bit_depth": 24,
              "codec": "mp3",
              "num_channels": 2
          },
          "clientMetadata": {"artist": "Miles Davis"}
          },
          {
          "objectUrl": "/path/to/my/bucket/song2.mp3",
          "audioMetadata": {
              "duration": 153.28,
              "file_size": 2900000,
              "mime_type": "audio/mpeg",
              "sample_rate": 44100,
              "bit_depth": 24,
              "codec": "mp3",
              "num_channels": 2
          },
          "clientMetadata": {"artist": "Atomic Kitten"}
          }
      ]
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
          "audio": [
              {
              "objectUrl": "Multi-Region-Access-Point-ARN + /path/to/my/bucket/cat.jpg",
              "audioMetadata": {
                  "duration": 180.98,
                  "file_size": 2900000,
                  "mime_type": "audio/mpeg",
                  "sample_rate": 44100,
                  "bit_depth": 24,
                  "codec": "mp3",
                  "num_channels": 2
              },
              "clientMetadata": {"artist": "Miles Davis"}
              },
              {
              "objectUrl": "/path/to/my/bucket/song2.mp3",
              "audioMetadata": {
                  "duration": 153.28,
                  "file_size": 2900000,
                  "mime_type": "audio/mpeg",
                  "sample_rate": 44100,
                  "bit_depth": 24,
                  "codec": "mp3",
                  "num_channels": 2
              },
          "clientMetadata": {"artist": "Atomic Kitten"}
              }
          ],
          "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
          "audio": [
              {
                  "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Music/2022/song_1.jpg",
                  "audioMetadata": {
                      "duration": 180.98,
                      "file_size": 2900000,
                      "mime_type": "audio/mpeg",
                      "sample_rate": 44100,
                      "bit_depth": 24,
                      "codec": "mp3",
                      "num_channels": 2
                  },
                  "clientMetadata": {
                      "colour": "black and white"
                  }
              },
              {
                  "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Music/2022/song_2.mp3",
                  "audioMetadata": {
                      "duration": 153.28,
                      "file_size": 2900000,
                      "mime_type": "audio/mpeg",
                      "sample_rate": 44100,
                      "bit_depth": 24,
                      "codec": "mp3",
                      "num_channels": 2
                  },
                  "clientMetadata": {
                      "colour": "brown"
                  }
              }
          ],
          "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a Folder to Store Your Audio Files">
    All files in Encord must be stored within folders. Therefore, you need to create a folder before registering any data with Encord. To create a folder:

    1. Navigate to **Data** > **Files & Folders**
    2. Click the **+ New folder** button to create a new folder. Select the type of folder you want to create.

    <div>
      <img />
    </div>

    3. Give the folder a meaningful name and description.

    4. Click **Create** to create the folder.
       The folder is listed in **Files & Folders**.
  </Step>

  <Step title="Upload Your Audio to Encord">
    <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

    1. Navigate to **Data** > **Files & Folders** in the Encord platform.
    2. Click into a Folder.
    3. Click **+ Upload files**.
       A dialog appears.

    <div>
      <img />
    </div>

    4. Click **Import from cloud data**.

    <div>
      <img />
    </div>

    <Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

    6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.
  </Step>
</Steps>

## STEP 2: Curate your Data

### Create a collection

A Collection is a container for data units (images or videos) that you can use to group your data units together.

Creation of a Collection involves [filtering and sorting your data](/platform-documentation/Curate/curation-basics#filters). Once you have selected a smaller group of images, videos or audio files, [create a Collection](/platform-documentation/Curate/curation-basics#collections).

1. Log in to the Encord platform.
   The landing page for the Encord platform appears.

2. Navigate to **Data** > **Explore**.
   The *All folders* page appears with a list of all folders in Encord.

3. Open a folder.

4. Click the **Explorer** button.
   The *Index Explorer* page appears.

   ![Access Index Explorer](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-access-index.gif)

5. Search, sort, and filter your data until you have the subset of the data you need.

   ![Sort and Filter](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/sort-and-filter.gif)

6. Select one or more of the images/frames/audio files in the Explorer workspace.
   A ribbon appears at the top of the Explorer workspace.

   <Note>Selecting a video frame selects the entire video. Specific frames from a video cannot be selected.</Note>

   ![Create Collection in Index](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-create-collection.gif)

7. Click **Select all** to select all the files in the subset.

   <Note>Use <kbd>Command + A</kbd> as a short cut to select all files.</Note>

8. Click **Add to a Collection**.

9. Click **New Collection**.

10. Specify a meaningful title and description for the Collection.

    <Note> The title specified here is applied as a tag/label to every selected image.</Note>

11. Click **Collections** to verify the Collection appears in the Collections list.

## Collection actions menu

Each collection in the Explorer filter panel has a **...** (horizontal dots) button that opens a collection actions submenu. The submenu provides quick access to all available actions for that collection.

The submenu displays:

* The **collection name** in bold at the top of the menu.
* The **collection ID** beneath the name. Click the copy icon next to the ID to copy it to your clipboard.
* **Actions grouped into sections** separated by dividers, making it easier to find the right action. Actions are organized into the following groups:
  * **Navigate** — for example, View in Explorer.
  * **Manage** — for example, Edit Details.
  * **Data** — for example, Add to Dataset and Download CSV.
  * **Workflow** — for example, Task Actions, Bulk Classify, Convert Collection, and Edit Object Class. These actions appear only when you are working within a project.
  * **Danger** — for example, Delete.

<Note>Sections with no available actions for your current context are hidden automatically — no empty dividers appear.</Note>

<Note>The grouped layout and copyable collection ID apply only to the collection actions submenu in the Explorer filter panel. The collections table row menu is unchanged.</Note>

## STEP 2: Set Up Your Project

<Steps>
  <Step title="Create a Dataset">
    Once you have a Collection, you can create a Dataset from your Collection.
  </Step>

  <Step title="Create an Ontology">
    <Note>We recommend learning about [Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) before creating Ontologies. </Note>

    <Warning>Ensure that Ontologies used for audio annotations only include Classifications and *Audio Region* objects </Warning>

    1. Click the **New ontology** button in the *Ontologies* section to create a new Ontology.

    <div>
      <img />
    </div>

    2. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.

    3. Click **Next** to continue.

    <div>
      <img />
    </div>

    4. Define your Ontology structure. Audio files are labeled using the Audio Region object type and Classifications.

    **To add an Audio Region object**:

    <div>
      <img />
    </div>

    1. Click **+ Add object** to create a new object.
    2. Give the object a name, for example "Male Vocals".
    3. Select the *Audio Region* object type.
    4. Optionally, configure the object to add any attributes.
    5. Optionally, enable the **Required** toggle to mark the object as *Required*.
    6. Repeat these steps for as many Audio Region objects as necessary.

    **Configure Objects**:

    Objects can be configured to add attributes.

    <div>
      <img />
    </div>

    1. Click the arrow button next to the object to start configuring.
    2. Click **+ Add attribute** to add an attribute.
    3. Select the attribute type: Text, radio button, or checklist. Select Text and check *Transcription* to transcribe audio files.
    4. Give the attribute a name, for example "Pitch", or "Lyrics".
    5. If your attribute is a radio button or a checklist click **Add option**.

    <div>
      <img />
    </div>

    6. Add the options you want your attribute to have. For "Pitch" this can be "High" and "Low".

    7. Optionally mark the object as [*Required*](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#mark-as-required) and / or [*Dynamic*](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes).

    8. Click the **Back to parent** button to return the Ontology creation view.

    **To add a Classification**:

    <div>
      <img />
    </div>

    1. Click **+ Add classification** to create a new classification.
    2. Give the classification a name. For example, "Tempo".
    3. Optionally, configure the classification to change the classification type. The default classification type is a text field.
    4. Optionally, enable the **Required** toggle to mark the classification as *Required*.
    5. Repeat these steps for as many classifications as necessary.

    **Configure classifications**:

    Classifications can be configured to change the classification type, and to add classification options to radio buttons and check lists.

    <div>
      <img />
    </div>

    1. Click the arrow icon next to an object to configure the classification.

    <div>
      <img />
    </div>

    2. Click the classification type to change the classification type. The default classification type is a text field.
    3. Click **Add option** to add an option if you have selected a radio button or check list classification.
    4. Enter a name for the classification option. For example, the classification "Tempo" can have the options "Slow", "Medium", and "Fast".
    5. Click the **Back to parent** button to return the Ontology creation view.
  </Step>

  <Step title="Create a Project">
    1. In the Encord platform, navigate to **Projects**.
    2. Click the **+ New annotation project** button to create a new Project.

    <div>
      <img />
    </div>

    3. Give the Project a meaningful title and description.

    <div>
      <img />
    </div>

    <Note>
      If you are part of an [Workspace](/platform-documentation/General/general-workspace-settings), an optional [Project tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags) drop-down is visible. Project tags are useful for categorizing and finding your Projects. Select as many tags as are relevant for your Project.
    </Note>

    4. Click the **Attach ontology** button.

    5. Select the [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) you created previously from the list using the **Select** button.

    <div>
      <img />
    </div>

    6. Click **OK** to attach the Ontology to the Project.

    7. Click the **Attach datasets** button.

    8. Select the [Dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets) you created previously from the list using the **Attach** button.

    <div>
      <img />
    </div>

    9. Click **OK** to attach the Dataset(s) to the Project.

    <div>
      <img />
    </div>

    10. Click the **Load from template** button to use a [Workflow template](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates).

    <div>
      <img />
    </div>

    11. Select the template you want to use and click **Load template**.

    12. Click **Create project** to finish creating the Project.

    <div>
      <img />
    </div>
  </Step>
</Steps>

## STEP 3: Label Your Audio Files

Navigate to the *Queue* tab of your Project and select the data unit you want to label.

**To label an audio region**:

1. Select a *Audio Region* class from the left side menu.

2. Click and drag your cursor along the waveform to apply the label between the desired start and end points. Repeat this as many times as necessary while the class is selected.

3. If required, apply any attributes to the region.

4. Repeat these steps for as many regions as necessary.

<Tip>
  Audio regions can be copy-pasted using <kbd>CMD</kbd> / <kbd>CTRL</kbd>  + <kbd>C</kbd> and <kbd>CMD</kbd>  <kbd>CTRL</kbd> + <kbd>V</kbd>.
</Tip>

<Tip>When assigning multiple *Audio Region* class labels to the same section of an audio file, hide overlapping labels.</Tip>

<div>
  <img />
</div>

**To apply the classification to the entire audio file**:

<iframe title="YouTube video player" />

1. Select the Classification from the left side menu.

2. For radio buttons and checklists, select the value(s) you want to classification to have. For text classifications, enter the desired text.

### Fill Range to the Playhead

You can quickly snap the boundary of a selected audio classification or audio region range to the current playhead (the visual marker on the timeline or waveform) position using the **Fill to playhead** action. This is useful when you want to extend a range to an exact point without manually dragging the timeline handle.

<Tip>
  Position the playhead at the desired boundary point, select the audio classification/audio region range, then press `Alt+V` (Windows/Linux) or `Option+V` (Mac) to extend the nearest range edge to the playhead. You can also click **Fill to playhead** in the **Available Actions** panel in the left sidebar.
</Tip>

The action automatically determines which edge to move:

* If the playhead is **past the end** of the range, the end boundary extends to the playhead.
* If the playhead is **before the start** of the range, the start boundary extends to the playhead.
* If the playhead is **inside** the range, the action does nothing — it only ever extends a range outward, never trims it.

<Note>
  **Fill to playhead** is only available for editable ranges. The action and hotkey have no effect on read-only or locked ranges.
</Note>

<Tip>
  Use **Fill to playhead** together with the other range-editing shortcuts for fast, keyboard-driven timeline work:

  | Action                          | Windows/Linux     | Mac                  |
  | ------------------------------- | ----------------- | -------------------- |
  | Fill selected range to playhead | `Alt+V`           | `Option+V`           |
  | Expand range right              | `Alt+Right`       | `Option+Right`       |
  | Shrink range right              | `Alt+Left`        | `Option+Left`        |
  | Expand range left               | `Alt+Shift+Left`  | `Option+Shift+Left`  |
  | Shrink range left               | `Alt+Shift+Right` | `Option+Shift+Right` |
</Tip>


# Audio for Direct Comparison (RLHF)
Source: https://docs.encord.com/end-to-end/Modalities/audio/audio-rlhf



Encord’s multimodal platform and configurable label editor make it possible to support data curation and annotation workloads on various types of media, and in various annotation configurations. Follow the end to end walkthrough below to learn how to setup an Audio annotation workload where each task allows you to directly compare two audio files. This could be applicable for example when rating two audio files against each other, or in RLHF flows.

## STEP 1: Create Metadata Schema

The schema organizes your custom metadata. Encord supports:

* Scalars: Methods for filtering and specifying data for custom Label Editor layouts.
* Enums: Methods with options for filtering.
* Embeddings: Method for embedding plot visualization, similarity search, and natural language search.

### Custom metadata

Custom metadata can store any information which is not the data itself in a key-value format. Custom metadata is often used to describe information useful in curation and management at scale. Encord also uses metadata to create annotation specific layouts in the editor. You set up both using a metadata schema.

<Tip>To handle your custom metadata schema across multiple teams within the same Workspace, we recommend using namespacing for metadata keys in the schema. This ensures that different teams can define and manage their own metadata schema without conflicts. For example, team A could use `video.description`, while team B could use `audio.description`. Another example could be `TeamName.MetadataKey`. This approach maintains clarity and avoids key collisions across departments.</Tip>

### Metadata schema table

<Tip>Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and blank spaces ( ), hyphens (-), underscores (\_), and periods (.). Metadata schema keys are case sensitive.</Tip>

Use `add_scalar` to add a scalar key to your metadata schema.

| Scalar Key | Description                                                                                                                                                                                | Display Benefits                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| boolean    | Binary data type with values "true" or "false".                                                                                                                                            | Filtering by binary values                                                            |
| datetime   | ISO 8601 formatted date and time.                                                                                                                                                          | Filtering by time and date                                                            |
| number     | Numeric data type supporting float values.                                                                                                                                                 | Filtering by numeric values                                                           |
| uuid       | UUIDv4 formatted unique identifier for a data unit.                                                                                                                                        | Filtering by customer specified unique identifier                                     |
| varchar    | Textual data type. Formally `string`. `string` can be used as an alias for `varchar`, but we STRONGLY RECOMMEND that you use `varchar`.                                                    | **Displaying data correctly in custom Label Editor layouts** and filtering by string. |
| text       | Text data with unlimited length (example: transcripts for audio). Formally `long_string`. `long_string` can be used as an alias for `text`, but we STRONGLY RECOMMEND that you use `text`. | Storing and filtering large amounts of text.                                          |

Use `add_enum` and `add_enum_options` to add an enum and enum options to your metadata schema.

| Key  | Description                                    | Display Benefits                                      |
| ---- | ---------------------------------------------- | ----------------------------------------------------- |
| enum | Enumerated type with predefined set of values. | Facilitates categorical filtering and data validation |

Use `add_embedding` to add an embedding to your metadata schema.

| Key       | Description                               | Display Benefits                                                                        |
| --------- | ----------------------------------------- | --------------------------------------------------------------------------------------- |
| embedding | 1 to 4096 for Index. 1 to 2000 for Active | Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon) |

<Warning>
  Incorrectly specifying a data type in the schema can cause errors when filtering your data in Index or Active. If you encounter errors while filtering, verify your schema is correct. If your schema has errors, correct the errors, re-import the schema, and then re-sync your Active Project.
</Warning>

### Import your metadata schema to Encord

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("metadata_1", data_type="boolean")
  metadata_schema.add_scalar("metadata_2", data_type="datetime")
  metadata_schema.add_scalar("metadata_3", data_type="number")
  metadata_schema.add_scalar("metadata_4", data_type="uuid")
  metadata_schema.add_scalar("metadata_5", data_type="varchar")
  metadata_schema.add_scalar("metadata_6", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("my-enum", values=["enum-value-01", "enum-value-02", "enum-value-03"])

  # Add embedding fields
  metadata_schema.add_embedding('my-test-active-embedding', size=512)
  metadata_schema.add_embedding('my-test-index-embedding', size=<values-from-1-to-4096>)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("G2G", data_type="boolean")
  metadata_schema.add_scalar("Date", data_type="datetime")
  metadata_schema.add_scalar("Cost", data_type="number")
  metadata_schema.add_scalar("Priority", data_type="number")
  metadata_schema.add_scalar("ID-Sys-01", data_type="uuid")
  metadata_schema.add_scalar("ID-Sys-02", data_type="uuid")
  metadata_schema.add_scalar("Description", data_type="varchar")
  metadata_schema.add_scalar("Location", data_type="varchar")
  metadata_schema.add_scalar("Translation en-gb", data_type="text")
  metadata_schema.add_scalar("Translation en-ca", data_type="text")
  metadata_schema.add_scalar("Translation en-us", data_type="text")
  metadata_schema.add_scalar("Translation zh-tw", data_type="text")
  metadata_schema.add_scalar("Translation zh-hk", data_type="text")
  metadata_schema.add_scalar("Translation zh-cn", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("Ready", values=["ripe", "partially-ripe", "unripe"])
  metadata_schema.add_enum("Fruit", values=["Blueberries", "Cherries", "Apples", "Kiwi"])

  # Add embedding fields
  metadata_schema.add_embedding('active-embedding-01', size=512)
  metadata_schema.add_embedding('active-embedding-02', size=512)
  metadata_schema.add_embedding('index-embedding-100', size=100)
  metadata_schema.add_embedding('index-embedding-1000', size=1000)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

***

## STEP 2: Create JSON for Import

<Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data).</Note>

<Tip>
  Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
</Tip>

The following is an example JSON file for uploading two audio files to Encord. Both files include `clientMetadata` to ensure they display correctly in custom Label Editor layouts.

* The `"encord-layout-group"` key determines which files are shown together — files with the same `"encord-layout-group"` value are displayed simultaneously. Both files in the example appears in the Label Editor simultaneously since they have the same `"encord-layout-group"` value.

* The `"encord-editor-grid-position"` key, set to either `A` or `B`, specifies the exact position of each file within the label editor.

One audio file includes `audioMetadata` and one does not.

<Tip>We **strongly recommend** including `audioMetadata` with each audio file when importing your audio files at scale. Including `audioMetadata` significantly improves the import speed of data when importing data at scale. When the `audioMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.</Tip>

<CodeGroup>
  ```json Template theme={"dark"}
  {
    "audio": [
      {
        "objectUrl": "<object url_1>",
        "clientMetadata": {"encord-editor-grid-position": "A", "encord-layout-group": "1"}
      },
      {
        "objectUrl": "<object url_2>",
        "title": "my-custom-audio-file-title.mp3",
        "audioMetadata": {
          "duration":  file-duration-in-seconds,
          "file_size": file-size-in-bytes,
          "mime_type": "MIME-type-of-the-audio-file-example-audio/mpeg",
          "sample_rate": sample-rate-in-Hz,
          "bit_depth": size-of-each-sample-in-bits,
          "codec": "file-codec-example-mp3",
          "num_channels": number-of-channels
          },
         "clientMetadata": {"encord-editor-grid-position": "B", "encord-layout-group": "1"}
      }
    ],
    "skip_duplicate_urls": true
  }
  ```

  ```json Example theme={"dark"}
  {
    "audio": [
      {
        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file_001.mp3",
        "title": "my-custom-audio-file-001.mp3",
        "audioMetadata": {
          "duration": 23.98,
          "file_size": 2900000,
          "mime_type": "audio/mp3",
          "sample_rate": 44100,
          "bit_depth": 24,
          "codec": "mp3",
          "num_channels": 2
          },
        "clientMetadata": {"encord-editor-grid-position": "A", "encord-layout-group": "1"}
      },
      {
        "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file_002.mp3",
        "title": "my-custom-audio-file-002.mp3",
        "audioMetadata": {
          "duration": 23.98,
          "file_size": 2900000,
          "mime_type": "audio/mp3",
          "sample_rate": 44100,
          "bit_depth": 24,
          "codec": "mp3",
          "num_channels": 2
          },
        "clientMetadata": {"encord-editor-grid-position": "B", "encord-layout-group": "1"}
      }
    ],
    "skip_duplicate_urls": true
  }
  ```
</CodeGroup>

***

## STEP 3: Import your Audio files

You can import your audio data, using the JSON file you created, using the UI or the SDK.

### Import with the UI

<Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

1. Navigate to **Data** > **Files & Folders** in the Encord platform.
2. Click into a Folder.
3. Click **+ Upload files**.
   A dialog appears.

<div>
  <img />
</div>

4. Click **Import from cloud data**.

<div>
  <img />
</div>

<Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.

### Import with the SDK

To use your data in Encord, it must be uploaded to the Encord **Files & Folders** storage. Once uploaded, your data can be reused across multiple Projects and contain no labels or annotations themselves. **Files & Folders** stores your data, while *Projects* store your labels. The following script creates a folder in **Files & Folders** and uses your AWS integration to register data in that folder.

The following script creates a new folder in **Files & Folders** and initiates uploads from AWS. It works for all file types.

<Tip>If `Upload is still in progress, try again later!` is returned, use the
[script to check the upload status](/sdk-documentation/getting-started-sdk/sdk-register-data-aws#step-5-check-data-upload) to see whether the upload has finished.</Tip>

Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<integration_title>` with the title of the integration you want to use.
* Replace `<folder_name>` with the folder name. The scripts assume that the specified folder name is unique.
* Replace `path/to/json/file.json` with the path to a [JSON file specifying which cloud storage files should be uploaded](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).
* Replace `A folder to store my files` with a meaningful description for your folder.
* Replace `"my": "folder_metadata"` with any metadata you want to add to the folder.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.
* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.
* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

<CodeGroup>
  ```python Create folder and register cloud data theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus  # Ensure correct import path

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

  # Specify the integration you want to use
  integrations = user_client.get_cloud_integrations()
  integration_idx = [i.title for i in integrations].index("<integration_title>")
  integration = integrations[integration_idx].id

  # Create a storage 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
  )

  # Initiate cloud data registration
  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
  )

  # Check upload status
  res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
  print(f"Execution result: {res}")

  if res.status == LongPollingStatus.PENDING:
      print("Upload is still in progress, try again later!")
  elif res.status == LongPollingStatus.DONE:
      print("Upload completed")
      if res.unit_errors:
          print("The following URLs failed to upload:")
          for e in res.unit_errors:
              print(e.object_urls)
  else:
      print(f"Upload failed: {res.errors}")

  ```

  ```Example output theme={"dark"}
  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.
  ```
</CodeGroup>

***

## STEP 4: Create a Dataset

1. Click the **New dataset** button in the *Datasets* section in *Annotate*.

<div>
  <img />
</div>

2. Give your Dataset a meaningful title and description. A clear title and description keeps your data organized.

<Tip>Toggle  **Looking to create a mirrored dataset?** to create a [Mirrored Dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets#mirrored-datasets). </Tip>

<div>
  <img />
</div>

3. Click **Create dataset** to create the Dataset.

### Attach files

<Tip>[You can add data to Datasets from the **Files & Folders** or the *Datasets* screens](/platform-documentation/Curate/index-files#add-data-to-datasets).</Tip>

<Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

1. Navigate to the *Datasets* section under the *Annotate* heading.
2. Click the Dataset you want to attach data to.
3. Click **+Attach existing files**.

<div>
  <img />
</div>

4. Select the folders containing the files you want to attach to the Dataset. To select individual files, double-click a folder to see its contents, and select the files you want to add to the Dataset.

5. Click **Attach data** to attach the selected files to the Dataset.

## STEP 5: Create an Ontology

1. Click the **New ontology** button in the *Ontologies* section to create a new Ontology.

<div>
  <img />
</div>

2. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized. Click **Next** to continue.

<div>
  <img />
</div>

3. Define your Ontology structure.

* Click **Add classification**
* Type 'Winner?'
* Click on **0 options** to configure options
* Click **Add option**
* Enter the word *Yes* as an option
* Click **Add option**
* Enter the word *No* as an option
* Click **Create ontology**

<div>
  <img />
</div>

***

## STEP 6: Create a Project

1. In the Encord platform, navigate to **Projects**.
2. Click the **+ New annotation project** button to create a new Project.

<div>
  <img />
</div>

3. Give the Project a meaningful title and description.

<div>
  <img />
</div>

<Note>
  An optional [Project tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags) drop-down is visible. Project tags are useful for categorizing and finding your Projects. Select as many tags as are relevant for your Project.
</Note>

4. Click the **Attach ontology** button.

5. Select the Ontology you created in STEP 5 and click the **Attach** button.

<div>
  <img />
</div>

6. Click **OK** to attach the Ontology to the Project.

7. Click the **Attach datasets** button.

8. Select the Dataset you created in STEP 4 and click the **Attach** button.

<div>
  <img />
</div>

9. Click **OK** to attach the Dataset(s) to the Project.

<div>
  <img />
</div>

10. Ensure the default Workflow shown suits your needs.

11. Click **Create project** to finish creating the Project.

<div>
  <img />
</div>

***

## STEP 7: Import Custom Layout

After creating your Project, import a custom layout for the Label Editor. Start by creating a JSON file that determines the layout.

### Create a JSON for the Layout

<CodeGroup>
  ```json Side by Side Layout theme={"dark"}
  {
    "grid": [
      [0], [1]
    ],
    "gridContent": {
      "0": {
        "client_metadata_query": {
          "or_conditions": [
            {
              "key": "encord-editor-grid-position",
              "operator": "=",
              "value": "A"
            },
            {
              "key": "encord-editor-grid-position",
              "operator": "=",
              "value": "B"
            }
          ]
        }
      },
      "1": {
        "client_metadata_query": {
          "or_conditions": [
            {
              "key": "encord-editor-grid-position",
              "operator": "=",
              "value": "A"
            },
            {
              "key": "encord-editor-grid-position",
              "operator": "=",
              "value": "B"
            }
          ]
        }
      }
    },
    "topLevelGridFilter": {
      "client_metadata": {
        "key": "encord-layout-group",
        "operator": "="
      }
    },
    "$schema": "https://raw.githubusercontent.com/encord-team/Annotate/main/editor-layouts/editor_layout_schema.json"
  }
  ```

  ```json Stacked Layout theme={"dark"}
  {
    "grid": [
      [0, 1]
    ],
    "gridContent": {
      "0": {
        "client_metadata_query": {
          "or_conditions": [
            {
              "key": "encord-editor-grid-position",
              "operator": "=",
              "value": "A"
            },
            {
              "key": "encord-editor-grid-position",
              "operator": "=",
              "value": "B"
            }
          ]
        }
      },
      "1": {
        "client_metadata_query": {
          "or_conditions": [
            {
              "key": "encord-editor-grid-position",
              "operator": "=",
              "value": "A"
            },
            {
              "key": "encord-editor-grid-position",
              "operator": "=",
              "value": "B"
            }
          ]
        }
      }
    },
    "topLevelGridFilter": {
      "client_metadata": {
        "key": "encord-layout-group",
        "operator": "="
      }
    },
    "$schema": "https://raw.githubusercontent.com/encord-team/Annotate/main/editor-layouts/editor_layout_schema.json"
  }
  ```
</CodeGroup>

### Import the JSON

1. Navigate to the Project settings.
2. Click on **Editor Layouts**.
3. Click **Upload JSON**.
4. Select the JSON file containing the layout you want the Label Editor to have.

<div>
  <img />
</div>

***

## STEP 8: Label and Submit Audio Data

More than a single file appears in the Label Editor. Switch back and forth between the files you are labeling or reviewing using the **Annotate from this tile** icon.

![Annotate from this file](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-change-tiles.png)

### Label Audio Files

Label audio files using the Classification specified from your Ontology.

<div>
  <img alt="Merge objects into a single object" title="merge-operations" />
</div>

**To label audio files:**

<Tip>We recommend using hotkeys to speed up and streamline your labeling process. For this example, the Classification hot keys are `2` and `Q`, but for you they might be different.</Tip>

1. Go to **Project > \[Your Project Title] > Queue > Annotate**.

   The *Project Annotate Queue* appears with a list of audio files for labeling.

   ![Project Queue](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-label-001.png)

2. Click **Initiate** next to a file from the Project Queue.

   Two audio files appear in the Label Editor.

3. Press `2` to select the *Winner* Classification.

   The options for the Classification appear.

   ![Label audio file 1](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-label-002.png)

4. Press `Q` to select *Yes*.

5. Click and then drag the sections of the audio file that appears at the top of the Label Editor.

6. Press `N` to save the Classifications on the audio file.

7. Click the **Annotate from this tile** icon to switch to annotating the bottom audio file.

   ![Annotate from this file](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-label-003.png)

8. Press `Q` to select *Yes*.

9. Click and then drag the sections of the audio file that appears at the top of the Label Editor.

10. Press `N` to save the Classifications on the audio file.

![Annotate from this file](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-label-004.png)

10. Click **Submit**.

    The next set of audio files for annotation appears.

***

## STEP 9: Review Audio Data

Approving tasks moves the tasks to the next stage in a workflow. In this example, that is *Complete*.

Rejecting tasks sends the tasks back to the first stage in a workflow. In this example, that is *Annotate*.

### Approve

<div>
  <img alt="Merge objects into a single object" title="merge-operations" />
</div>

**To approve labels on audio files:**

1. Go to **Project > \[Your Project Title] > Queue > Review**.

   The *Project Review Queue* appears with a list of audio files for labeling.

   ![Project Queue](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-review-001.png)

2. Click **Initiate** next to a file from the Project Queue.

   Two audio files appear in the Label Editor.

   ![Review labels](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-review-002.png)

3. Expand the *Winner* Classification.

   The options for the Classification appear.

4. Select the Classifications applied to the audio file.

5. Press `N` to approve the Classifications on the audio file.

6. Press the **Review from this file** icon.

   ![Project Queue](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-review-003.png).

7. Expand the *Winner* Classification.

   The options for the Classification appear.

   ![Project Queue](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-review-004.png).

8. Select the Classifications applied to the audio file.

9. Press `N` to approve the Classifications on the audio file.

10. Click **Approve task** to move the task to the next stage.

    ![Project Queue](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-review-005.png).

    In this example, that is the **Complete** stage.

    ![Project Queue](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-complete-001.png).

### Reject

**To reject labels on audio files:**

1. Go to **Project > \[Your Project Title] > Queue > Review**.

   The *Project Review Queue* appears with a list of audio files for labeling.

   ![Reject task](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-review-001.png)

2. Click **Initiate** next to a file from the Project Queue.

   Two audio files appear in the Label Editor.

   ![Reject task](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-reject-002.png)

3. Expand the *Winner* Classification.

   The options for the Classification appear.

4. Select the Classifications applied to the audio file.

5. Press `B` to reject the Classifications on the audio file.

   A dialog appears.

6. Provide a reason for rejecting the Classification.

7. Press the **Review from this file** icon.

   ![Reject task](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-reject-003.png).

8. Expand the *Winner* Classification.

   The options for the Classification appear.

   ![Reject task](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-reject-004.png).

9. Select the Classifications applied to the audio file.

10. Press `B` to reject the Classifications on the audio file.

11. Click **Reject task** to reject the tasks.

![Reject task](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-reject-005.png).

Both tasks then appear in the **Annotate** stage.

### Complete

Files in the *Complete* stage can be reopened.

![Complete](https://storage.googleapis.com/docs-media.encord.com/static/img/syn-getting-started/syn-getting-started-complete-001.png).


# DICOM End-to-End
Source: https://docs.encord.com/end-to-end/Modalities/dicom/dicom-annotation



<span>
  DICOM
</span>

## Import Data

In this section we're going to download and register our data.

<Steps>
  <Step title="Download Sample Data">
    Download and extract the [`DICOM-Lung-Lesion.zip` sample DICOM dataset](https://storage.googleapis.com/docs-media.encord.com/E2E%20Artifacts/DICOM-Lung-Lesion.zip).
  </Step>

  <Step title="Create a Mirrored Dataset">
    You’ll need to create a Mirrored Dataset before registering any data. Navigate to the **Datasets** section of the platform.

    <div>
      <iframe />
    </div>
  </Step>

  <Step title="Import DICOM Series">
    <Info>
      This step assumes you want to import DICOM files from your local machine. To learn how to register cloud data [click here](/platform-documentation/Curate/add-files/index-register-cloud-data-cloud-sync).
    </Info>

    Now import the sample data from `DICOM-Lung-Lesion.zip` into the Dataset `E2E - Dataset - DICOM`. The platform automatically detects that all files belong to the same DICOM series and groups them into a single data unit.

    <div>
      <iframe />
    </div>
  </Step>
</Steps>

## Create Ontology

<Tip>We recommend learning about [Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) in Encord before creating Ontologies. </Tip>

1. Click the **+ New ontology** button in the **Ontologies** section.

<div>
  <img />
</div>

2. Name your Ontology `DICOM - E2E - Ontology` and provide an optional description.
3. Click **Next** to continue.
4. Define your Ontology structure.

<div>
  <iframe />
</div>

## Create Project

1. Click the **+ New annotation project** button in the **Projects** section.

<div>
  <img />
</div>

2. Name your Project `DICOM - E2E - Project` and provide an optional description.
3. Attach your Ontology and Dataset.
4. Click **Create project**.

<div>
  <iframe />
</div>

## Annotate DICOM

<div>
  <iframe />
</div>

## Export Labels

<div>
  <iframe />
</div>

1. Click **Export** while in your Project.
   The *Export labels* dialog appears.
2. Specify the following:
   * **Format:** Specify the format to export the labels (JSON or COCO).
   * **Stage:** Specify the Workflow stage to export the labels from.
   * **Generate signed URLs:** Specify whether to generate signed URLs for the data units that have labels.
   <Note>
     Enabling this option can significantly increase export times.
   </Note>
   * **Save as new version:** Specify to version the labels.
   * **Labels to include:** Specify the labels to include. You can export all labels or select specific object or classification labels to export.
3. Click **Export**.
   A *Labels export in progress* toast message appears.


# Visual Data End-to-End
Source: https://docs.encord.com/end-to-end/Modalities/e2e-data-images-videos



## What are we doing?

Using a very small dataset of fruit (apples, bananas, blueberries, cherries, kiwi, persimmons, and strawberries) you will learn how to use Encord with images and videos.

For all the tasks in this end-to-end process, all artifacts, relevant information, and code is provided. How you want to proceed is up to you. Each section provides a path to use Encord from basic use to SOTA (state-of-the-art) complexity. Pick the path at each STEP that suits your needs best.

## Our Goals

Our basic goals are this:

* **Import data:** Get our data into Encord. We might want to manage and curate our data, but that is going to depend on how much data we have or how complex our Projects are.

* **Label data:** Label our data and export the labels. This is going to involve creating a Project and then actually labeling and reviewing our labels. Once our labels are okay we can export them from Encord.

* **Validate our labels:** At scale, using Active streamlines and significantly speeds up validating our labels.

* **Evaluate our model:** Compare and optimize our model's performance using Active.

How you intend to use your data in Encord dictates the best way to use Encord. Using cloud integrations, the SDK, or Agents adds complexity to using Encord, but at scale, this complexity adds significant value.

## STEP 1: Import Data

Performing ANY of these tasks results in creating the Dataset `E2E Fruit Dataset` for use with the Project.

<CardGroup>
  <Card title="Import Local Data - UI" href="/end-to-end/Modalities/images-videos/data-import-basic-local-images-videos">
    Testing and basic annotation Projects using local data.
  </Card>

  <Card title="Import/Register Cloud Data - UI - Cloud-synced" href="/end-to-end/Modalities/images-videos/data-import-cloud-synced-folder-images-videos">
    Testing and basic annotation Projects using cloud data.
  </Card>

  <Card title="Import/Register Cloud Data - UI" href="/end-to-end/Modalities/images-videos/data-import-basic-cloud-images-videos">
    Testing and basic annotation Projects using cloud data.
  </Card>

  <Card title="Import/Register Cloud Data - SDK" href="/end-to-end/Modalities/images-videos/data-import-basic-cloud-images-videos-sdk">
    Programmatic testing and basic annotation Projects using cloud data.
  </Card>

  <Card title="Import + Curate Cloud Data - UI" href="/end-to-end/Modalities/images-videos/data-curation-images-videos">
    Manage and curate large amounts of data for one or more Projects, using Index Premium.
  </Card>

  <Card title="Import + Curate Cloud Data - SDK" href="/end-to-end/Modalities/images-videos/data-curation-images-videos-sdk">
    Programmatic managing and curating large amounts of data for one or more Projects, using Index Premium.
  </Card>
</CardGroup>

## STEP 2: Create Project

Performing ANY of these tasks results in creating the Project `E2E Fruit Project` to annotate.

<Note>
  * The Ontology is the same for ALL tasks.
  * The Workflow varies depending on the task.
</Note>

<CardGroup>
  <Card title="Create Project - UI" href="/end-to-end/Modalities/images-videos/project-create-basic-images-videos">
    Create Projects (Ontologies, Workflows, and Projects) using the Encord UI.
  </Card>

  <Card title="Create Project - SDK" href="/end-to-end/Modalities/images-videos/project-create-images-videos-sdk">
    Create Projects (Ontologies, Workflows, and Projects) using the SDK.
  </Card>

  <Card title="Create Consensus Project - UI" href="/end-to-end/Modalities/images-videos/project-create-consensus-images-videos">
    Create Consensus Projects (Ontologies, Workflows, and Projects) using the UI.
  </Card>

  <Card title="Create Consensus Project - SDK" href="/end-to-end/Modalities/images-videos/project-create-consensus-images-videos-sdk">
    Create Consensus Projects (Ontologies, Workflows, and Projects) using the UI.
  </Card>

  <Card title="Create Project - Import Labels" href="/end-to-end/Modalities/images-videos/project-create-import-labels-images-videos">
    Create Projects (Ontologies, Workflows, and Projects) for use with your own labels.
  </Card>

  <Card title="Create Project - Import Predictions" href="/end-to-end/Modalities/images-videos/project-create-import-predictions-images-videos">
    Create Projects (Ontologies, Workflows, and Projects) for use with your own model predictions.
  </Card>
</CardGroup>

## STEP 3: Label Data

Performing ANY of these tasks results in labeling the data and reviewing the labels on the data in the Project `E2E Fruit Project`.

<CardGroup>
  <Card title="Manually Label" href="/end-to-end/Modalities/images-videos/annotation-labelling-manual-images-videos">
    Manually annotate and review your data and then export your labels.
  </Card>

  <Card title="Use SAM 2" href="/end-to-end/Modalities/images-videos/annotation-labelling-sam2-images-videos">
    Use SAM 2 and SAM 2 tracking to annotate your data, review using humans, and then export your labels using the UI or the SDK.
  </Card>

  <Card title="Use SAM 2 - Consensus" href="/end-to-end/Modalities/images-videos/annotation-labelling-consensus-sam2-images-videos">
    Use SAM 2 and SAM 2 tracking to annotate your data on a Consensus Project, review using humans, and then export your labels using the UI or the SDK.
  </Card>

  <Card title="Import Labels" href="/end-to-end/Modalities/images-videos/annotation-import-labels-images-videos">
    Use your model's labels and review your data (with humans in the loop).
  </Card>

  <Card title="Import Predictions" href="/end-to-end/Modalities/images-videos/annotation-import-predictions-images-videos">
    Use your model's predictions.
  </Card>
</CardGroup>

## STEP 4: Label Verification

Label verification can be performed visually in Annotate as a reviewer. However, at scale, using Active to verify the quality of your labels significantly improves the effectiveness and speed of label verification.

<CardGroup>
  <Card title="Label Verification - UI" href="/end-to-end/Modalities/images-videos/label-verification-images-videos">
    Verify the quality of your labels using Active.
  </Card>

  <Card title="Label Verification - SDK" href="/end-to-end/Modalities/images-videos/label-verification-images-videos-sdk">
    Programmatically verify the quality of your labels using Active.
  </Card>
</CardGroup>

## STEP 5: Model Evaluation

Use Active to compare and optimize your model's performance.

<CardGroup>
  <Card title="Model Evaluation" href="/end-to-end/Modalities/images-videos/model-eval-images-videos">
    Compare and optimize your model's performance using Active.
  </Card>

  <Card title="Model Evaluation - SDK" href="/end-to-end/Modalities/images-videos/model-eval-images-videos-sdk">
    Programmatically compare and optimize your model's performance using Active.
  </Card>
</CardGroup>


# Scene Annotation End-to-End
Source: https://docs.encord.com/end-to-end/Modalities/pcd/e2e-pcd



This tutorial shows the shortest production-style path for working with point cloud and multimodal Scenes in Encord: prepare sensor assets, register Scenes, create a Project, annotate, review, and reuse the Scene data.

<Note>
  Enable hardware acceleration in Chrome before annotating large point clouds or multimodal Scenes.
</Note>

## What You Need

* A cloud storage integration that can access your point cloud and image assets.
* A folder in **Files & Folders** for the registered Scenes.
* A Dataset and Project for annotation work.
* An Ontology with the Scene tools you need, such as cuboids, polylines, keypoints, or classifications.

## 1. Prepare Scene Assets

Put each Scene's files in a stable cloud prefix. For example:

```text theme={"dark"}
s3://my-bucket/scenes/scene-001/
  lidar/000000.pcd
  lidar/000001.pcd
  front/000000.jpg
  front/000001.jpg
```

Use the same frame index for files that should appear together. If your sensors are asynchronous, use sensor timestamps instead and keep the timestamps consistent across streams.

## 2. Register Scenes

Use the Python SDK to build and upload Scenes. The SDK is preferred over hand-authored JSON because it validates stream names, references, camera links, and frame-of-reference relationships before registration.

```python Build and Upload a Scene expandable theme={"dark"}
from uuid import UUID

from encord.beta.scene import SceneBuilder, identity_pose, intrinsics_pinhole
from encord.storage import StorageFolder


def build_scene() -> SceneBuilder:
    scene = SceneBuilder()

    # Anchor the sensor streams to the moving platform.
    ego = scene.add_for_stream("ego")
    ego.add_pose(identity_pose(), timestamp=0)

    # Matching timestamps make the point cloud and image appear together.
    scene.add_pcd_stream("lidar", frame_of_reference=ego).add_pcd(
        uri="s3://my-bucket/scenes/scene-001/lidar/000000.pcd",
        timestamp=0,
    )

    # Inline camera parameters create a camera stream named "front/camera".
    scene.add_image_stream(
        "front",
        width=1920,
        height=1080,
        intrinsics=intrinsics_pinhole(fx=1000, fy=1000, ox=960, oy=540),
        timestamp=0,
        frame_of_reference=ego,
    ).add_image(
        uri="s3://my-bucket/scenes/scene-001/front/000000.jpg",
        timestamp=0,
    )

    return scene


def register_scene(storage_folder: StorageFolder, integration_id: str) -> UUID:
    scene = build_scene()

    # Pass the SceneBuilder itself. upload_scene validates and serializes it internally.
    return storage_folder.upload_scene(
        scene=scene,
        title="scene-001",
        integration_id=integration_id,
        client_metadata={"source": "sample"},
    )
```

For sequences, additional sensors, and distortion models, see [Create and Register Scenes](/platform-documentation/Curate/add-files/add-pcd-data) and [Scene SDK Workflows](/sdk-documentation/index-sdk/sdk-scenes).

## 3. Create the Annotation Project

1. Add the registered Scene items to a Dataset.
2. Create or reuse an Ontology for the labels you need.
3. Create a Project from the Dataset and Ontology.
4. Assign work through your Workflow as usual.

Use metadata such as `route`, `split`, `capture_date`, or `scenario` on Scene items if you need to filter, prioritize, or route tasks later.

## 4. Annotate Scenes

Open a task and use the Scene editor to inspect the point cloud, camera views, and synchronized frames.

Recommended first pass:

* Confirm the point cloud orientation and scale look correct.
* Check that camera images align with the point cloud if calibration is present.
* Use the built-in Scene navigation tutorial to choose mouse or trackpad controls.
* Create the first few labels, move through frames, and verify object continuity.

For editor workflows, see [Annotating Scenes](/platform-documentation/Annotate/annotate-label-editor/annotate-pcd).

## 5. Review and Reuse Scene Data

After annotation, spot-check a few completed tasks in review. Pay special attention to frame alignment and camera projection quality; most Scene issues are easiest to catch visually.

Use `SceneReader` when you need to inspect, copy, or migrate registered Scene assets.

```python Read and Copy a Scene expandable theme={"dark"}

from uuid import UUID

from encord.beta.scene import SceneReader
from encord.orm.storage import DataUploadItems, StorageItemType
from encord.storage import StorageFolder, StorageItem


def find_scene(storage_folder: StorageFolder, title: str) -> StorageItem:
    scene_items = storage_folder.list_items(
        search=title,
        item_types=[StorageItemType.SCENE],
        page_size=1,
    )
    scene_item = next(iter(scene_items), None)
    if scene_item is None:
        raise ValueError(f"Scene with title '{title}' not found.")
    return scene_item


def get_lidar_signed_url(scene_item: StorageItem, timestamp: float = 0) -> str:
    scene = SceneReader(scene_item).read()
    lidar = scene.get_stream("lidar", kind="point_cloud")
    return lidar.get_event(timestamp=timestamp).signed_url


def get_image_signed_urls(scene_item: StorageItem, timestamp: float = 0) -> list[tuple[str, str]]:
    scene = SceneReader(scene_item).read()
    return [(stream_id, event.signed_url) for stream_id, event in scene.get_images_at_timestamp(timestamp)]


def copy_scene_to_folder(
    scene_item: StorageItem,
    target_storage_folder: StorageFolder,
    *,
    integration_id: str,
    title: str,
    source_uri_prefix: str,
    target_uri_prefix: str,
) -> UUID:
    payload = SceneReader(scene_item).to_upload_payload(
        title=title,
        uri_mapper=lambda uri: uri.replace(source_uri_prefix, target_uri_prefix),
    )

    return target_storage_folder.add_private_data_to_folder_start(
        integration_id=integration_id,
        private_files=DataUploadItems(scenes=[payload]),
    )
```

## Troubleshooting

| Symptom                     | Check                                                                      |
| --------------------------- | -------------------------------------------------------------------------- |
| Scene does not load         | Confirm the integration can access every URI used in the Scene.            |
| Camera view is offset       | Check camera intrinsics, sensor pose, and world/camera conventions.        |
| Streams advance out of sync | Check the timestamps assigned to each stream event.                        |
| Editor feels slow           | Enable browser hardware acceleration and test with a smaller sample Scene. |


# Entity Mapping End-to-End
Source: https://docs.encord.com/end-to-end/Modalities/tabular/e2e-tabular-data



<span>
  Entity Mapping
</span>

<span>
  Basic Cloud Storage
</span>

<span>
  Tabular Data
</span>

## Why do this?

You want to reconcile messy, fragmented, or duplicated rows into consistent, unique entities for your down stream models.

**You want to understand how to create Projects in Encord that use Tabular Data (CSV files). This example assumes your Tabular Data is stored in cloud storage.**

<Tip>If you intend to use Encord at scale, we strongly recommend using the Encord SDK.</Tip>

### Pros and Cons

<table>
  <thead>
    <tr>
      <th>Pros</th>
      <th>Cons</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        * Simple way to get data into Encord
        * Tabular data available for annotation
      </td>

      <td>
        * Requires a little bit of technical knowledge to set integrations
        * No data management or curation of your tabular data in this example
      </td>
    </tr>
  </tbody>
</table>

<Note>
  Tabular data currently supports [**CONSENSUS** Projects](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus) only.
</Note>

## Import/Register Data

We're going to register our tiny dataset of CSV files.

<Steps>
  <Step title="Create Integration">
    Select your cloud provider.
  </Step>

  <Step title="Download Data">
    Download and extract the contents of [e2e-tabular-data.zip file](https://storage.googleapis.com/docs-media.encord.com/E2E%20Artifacts/Tab%20Data/e2e-tabular-data.zip).
  </Step>

  <Step title="Modify JSON">
    Modify the `tabular-data.json` file in the e2e-tabular-data.zip file.

    1. Open the `tabular-data.json` file and replace `<file-path>` with the file path to the data stored in your cloud storage.

    <Note>The `tabular-data.json` file includes the file path and title for each CSV file. It does NOT include `clientMetadata`.</Note>
  </Step>

  <Step title="Create a Mirrored Dataset">
    Create a mirrored Dataset called `E2E - Tabular Data - Dataset` using the UI. Using mirrored Datasets is a simple way to sync data from folders to Datasets. Mirrored Datasets provide no method of curating or managing your data.

    If you want to add more data to your Dataset, add more data to the JSON file. Then re-import the JSON file and data automatically gets added to your Dataset and Project.

    <iframe title="Loom Video" />
  </Step>

  <Step title="Register/Import Data">
    Use the `tabular-data.json`, from the `e2e-tabular-data.zip`, to register/import the data to the mirrored Dataset.

    <iframe title="Loom Video" />
  </Step>
</Steps>

## Create Ontology

For this step you need the following:

* `genre-options.csv` and `platform-options.csv` from the `e2e-tabular-data.zip` file.
* One `video_game_annotation_X.csv` from the `e2e-tabular-data.zip` file.
* `tabular_create_ontology.py` script. You create this.

The `tabular_create_ontology.py` script does the following:

* Creates the Ontology based on the structure of any of the `video_game_annotation_X.csv` files.
* Creates feature mapping for the *genre* column using `genre-options.csv`.
* Creates feature mapping for the *platform* column using `platform-options.csv`.

<iframe title="Loom Video" />

`E2E - Tabular Data - Ontology` appears in your Ontology list after running the script.

```python tabular_create_ontology script theme={"dark"}

import pandas as pd
from encord.objects import OntologyStructure, Shape, TextAttribute
from encord.objects.attributes import RadioAttribute
from encord.user_client import EncordUserClient

# --- Configuration ---
ENCORD_SSH_KEY = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SHH private key
TASK_CSV_PATH = "/file/path/to/video_game_annotation_1.csv" # Replace with the file path to any of the video_game_annotation_X.csv files

READ_ONLY_COLUMNS = [0, 1, 2]
ANNOTATION_COLUMNS = [3, 4]

# Replace these paths with actual mapping column name > options file
MAPPING_FIELD_OPTION_PATHS = {
    "genre": "/file/path/to/genre-options.csv",
    "platform": "/file/path/to/platform-options.csv",
}

ONTOLOGY_NAME = "E2E - Tabular Data - Ontology"
OBJECT_NAME = "Game Row"


def parse_csv():
    csv_df = pd.read_csv(TASK_CSV_PATH)
    readonly_columns = csv_df.columns[READ_ONLY_COLUMNS].tolist()
    mapping_columns = csv_df.columns[ANNOTATION_COLUMNS].tolist()

    return mapping_columns, readonly_columns


def create_ontology(text_attribute_names, radio_option_names):
    ontology_structure = OntologyStructure()
    text_object = ontology_structure.add_object(name=OBJECT_NAME, shape=Shape.TEXT)

    for attribute in text_attribute_names:
        text_object.add_attribute(TextAttribute, attribute)

    for column_name in radio_option_names:
        options_path = MAPPING_FIELD_OPTION_PATHS.get(column_name)
        if options_path is None:
            raise ValueError(f"No options file defined for column '{column_name}'")

        options = pd.read_csv(options_path).iloc[:, 0].dropna().astype(str).tolist()

        radio_attribute = text_object.add_attribute(RadioAttribute, column_name, required=True)
        for option in options:
            radio_attribute.add_option(option)

    user_client = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=ENCORD_SSH_KEY,
        domain="https://api.encord.com",
    )
    return user_client.create_ontology(ONTOLOGY_NAME, structure=ontology_structure)


if __name__ == "__main__":
    mapping_columns, readonly_columns = parse_csv()
    ontology = create_ontology(readonly_columns, mapping_columns)
    print(f"Created ontology {ontology.title}, id: {ontology.ontology_hash}")

```

## Create Project

Create a **CONSENSUS** Project, after creating the Mirrored Dataset and registering/importing the CSV files, and creating the Ontology.

<Note>
  * Tabular data currently supports **CONSENSUS** Projects only.
  * An AGENT block must be the first block for tabular data.
  * The AGENT block and AGENT pathway **MUST be the exact name** specified below.
</Note>

* Name: `E2E - Tabular Data - Project`
* Agent name: `Pre-label`
* Agent pathway: `Labelled`

<Important>
  - Record the `Project ID` for use later.
  - Add your annotators, reviewers, team managers, and Project Admin after creating the Project.
  - Adjust the number of annotators per task to your own requirements.
</Important>

<iframe title="Loom Video" />

## Run the Agent script

The `tabular_run_agent.py` populates tasks in the AGENT block in your workflow.

Create the following Python scripts. Both scripts must be in the same directory.

* `tabular_run_agent.py`
* `tabular_utils.py`

After creating the scripts, run the `tabular_run_agent.py` script.

After running the script, tasks that were in the AGENT stage are now in the CONSENSUS - ANNOTATE stage.

<iframe title="Loom Video" />

<CodeGroup>
  ```py tabular_run_agent script theme={"dark"}

  from typing import Annotated
  from pathlib import Path
  import os

  from encord_agents.tasks import Runner
  from encord.objects.ontology_labels_impl import LabelRowV2
  from encord.project import Project
  from encord_agents.tasks.dependencies import dep_asset
  from encord_agents.core.dependencies import Depends
  from encord.objects.common import Shape

  from tabular_utils import parse_csv_and_add_objects

  # --- Configuration ---
  ENCORD_SSH_KEY = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
  PROJECT_HASH = "00000000-0000-0000-0000-000000000000" # Replace with unique Project ID of the tabular data Project
  AGENT_STAGE = "Pre-label"
  AGENT_PATHWAY = "Labelled"

  # Inject into environment so Encord Agents can pick it up
  os.environ["ENCORD_SSH_KEY_FILE"] = ENCORD_SSH_KEY

  runner = Runner(project_hash=PROJECT_HASH)

  @runner.stage(stage=AGENT_STAGE)
  def agent_logic(
      lr: LabelRowV2, project: Project, asset: Annotated[Path, Depends(dep_asset)]
  ):
      ontology = project.ontology_structure
      text_object = ontology.objects[0]
      if text_object is None:
          raise Exception("No objects found")
      elif text_object.shape is not Shape.TEXT:
          raise Exception("Text object required")

      parse_csv_and_add_objects(text_object, lr, asset)

      return AGENT_PATHWAY

  if __name__ == "__main__":
      runner.run()
  ```

  ```py tabular_utils script theme={"dark"}

  import pandas as pd
  from pathlib import Path

  from encord.exceptions import OntologyError
  from encord.objects.attributes import Attribute
  from encord.objects.coordinates import TextCoordinates
  from encord.objects.frames import Range
  from encord.objects.ontology_labels_impl import LabelRowV2
  from encord.objects.ontology_object import Object

  def parse_csv_and_add_objects(
      text_object: Object, label_row: LabelRowV2, asset_link: Path
  ):
      csv_df = pd.read_csv(asset_link)
      filtered_columns = csv_df.columns

      read = None
      with asset_link as f:
          read = f.read_bytes()

      for index, row in csv_df.iloc[0:].iterrows():
          byte_range = get_byte_range_for_row(read, index + 1)
          if byte_range is None:
              raise Exception("Row does not exist")
          (start, end) = byte_range

          row_dict = row[filtered_columns].to_dict()

          add_text_object(text_object, label_row, Range(start=start, end=end), row_dict)

      label_row.save()


  def get_byte_range_for_row(csv_content: bytes, row: int) -> tuple[int, int] | None:
      # Find all newline positions
      newline_positions = []
      current_pos = 0

      while True:
          newline_pos = csv_content.find(b"\n", current_pos)
          if newline_pos == -1:
              break
          newline_positions.append(newline_pos)
          current_pos = newline_pos + 1

      # Check if requested row exists
      if row > len(newline_positions):
          return None

      # Calculate start and end positions
      if row == 0:
          start_byte = 0
      else:
          start_byte = newline_positions[row - 1] + 1

      if row < len(newline_positions):
          end_byte = newline_positions[row]
      else:
          # Last row might not have a trailing newline
          end_byte = len(csv_content)

      return (start_byte, end_byte)


  def add_text_object(
      text_object: Object,
      lr: LabelRowV2,
      byte_range: Range,
      csv_column_to_value: dict[str, str],
  ):
      new_instance = text_object.create_instance()
      new_instance.set_for_frames(coordinates=TextCoordinates(range=[byte_range]))
      for key, value in csv_column_to_value.items():
          try:
              attribute = text_object.get_child_by_title(title=key, type_=Attribute)
              if attribute.required:
                  # If required attribute then this is the one they are writing so ignore
                  continue
              new_instance.set_answer(attribute=attribute, answer=str(value))
          except OntologyError:
              # Ignore columns that don't have attributes
              pass
      lr.add_object_instance(new_instance)

  ```
</CodeGroup>

## Annotate Tabular Project

Annotation of CSV files depends on your Ontology. Our Ontology `E2E - Tabular Data - Ontology` uses text regions, but your annotators and reviewers use drop downs.

In this section, you'll see the following Collaborators:

* **Annotators** labeling data
* **Reviewers** reviewing labels created by Annotators
* **Team Manager** managing the Annotators and Reviewers
* **Project Admin** managing the Project and exporting labels

<Steps>
  <Step title="Prepare to Label">
    <AccordionGroup>
      <Accordion title="Team Manager or Project Admin">
        The Team Manager or Project Admin can prioritize certain data to be labeled and reviewed first. Let's prioritize two data units to be labeled first by setting the priority for those files to `75`.

        **Set Priority to `75`**

        <iframe title="Loom Video" />
      </Accordion>

      <Accordion title="Annotators">
        Annotators can sort by priority, search by file name, or filter Dataset or Issue Status.

        <iframe title="Loom Video" />
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Label Data">
    <AccordionGroup>
      <Accordion title="Team Manager or Project Admin">
        The Team Manager or Project Admin can monitor the performance and progress of the annotation team.

        <iframe title="Loom Video" />
      </Accordion>

      <Accordion title="Annotators">
        Annotators use drop downs to select the genre and platform for each row.

        <iframe title="Loom Video" />
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Review Labels">
    <AccordionGroup>
      <Accordion title="Team Manager or Project Admin">
        The Team Manager or Project Admin can monitor the performance and progress of the review team.

        <iframe title="Loom Video" />
      </Accordion>

      <Accordion title="Review Labels">
        Reviewers verify that the labels are correct.

        <Note>Use any column in a row to select correct answers.</Note>

        <Tip>
          When there is an issue with labels/classifications, Reviewers can:

          * Reject the task and add a comment about why a task was rejected. Rejected tasks go back to the person who added the labels/classifications.
          * Edit labels directly using the **Edit labels** button and then approve the task.
        </Tip>

        <iframe title="Loom Video" />
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Export Labels">
    Only Project Admins can export labels from Encord.

    <Accordion title="Project Admin">
      Export the labels from the Project Labels page.

      <iframe title="Loom Video" />
    </Accordion>
  </Step>
</Steps>


# Text / HTML End-to-End
Source: https://docs.encord.com/end-to-end/Modalities/text/text-annotation



<Warning>
  This guide assumes your text files are stored in AWS. To learn how to create integrations with other cloud providers [click here](/platform-documentation/General/annotate-data-integrations). To learn how to upload files locally [click here](/platform-documentation/Curate/add-files/index-upload-local-data).
</Warning>

## STEP 1: Register Your Text Files

<Steps>
  <Step title="Set Up AWS">
    Before you can do anything with the Encord platform and cloud storage, you need to configure your cloud storage to work with Encord. Once the integration between Encord and your cloud storage is complete, you can then use your data in Encord.

    In order to integrate with AWS S3, you need to:

    1. Create a permission policy for your resources that allows appropriate access to Encord.
    2. Create a role for Encord and attach the policy so that Encord can access those resources.
    3. Activate Cross-origin resource sharing which allows Encord to access those resources from a web browser.
    4. Test the integration to make sure it works.

    <Tip>See our [AWS integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration) for a detailed explanation of setting up AWS to work with Encord.</Tip>

    You have the following options to integrate AWS and Encord:

    <div lang="en">
      <head>
        <meta />

        <meta name="viewport" />

        <title>Clickable Div</title>
      </head>

      <div>
        <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration">
          Use AWS UI
        </a>

        <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration#terraforming-your-aws-s3-integration">
          Use Terraform
        </a>
      </div>
    </div>
  </Step>

  <Step title="Create AWS Integration in Encord">
    <Note>Create an S3 bucket to store your files if you haven't already. Your S3 bucket permissions should be set to be blocking all public access.</Note>

    In the *Integrations* section of the Encord platform, click **+New integration** to create a new integration.

    <div>
      <img />
    </div>

    Select *AWS S3* at the top of the chooser.

    <div>
      <img />
    </div>

    <Note>It is essential you do not close this tab or window until you have finished the whole integration process. If you use the AWS UI for integration, we advise opening the AWS console in a separate tab.</Note>

    <Tip>See our [AWS integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration) for a detailed explanation of how to set up the AWS integration.</Tip>
  </Step>

  <Step title="Create JSON file for Registration">
    <Tip> See our documentation [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) for more comprehensive information</Tip>

    Create a JSON file based on the templates provided below.

    The `title` field is optional. If omitted, the file path and file name are used as the default title. For example, if the file is located at `https://encord-solutions-bucket.s3.eu-west-2.amazonaws.com/path/to/my/bucket/website.html`, the title defaults to `/path/to/my/bucket/website.html`.

    | Key or Flag      | Required? | Default value           |
    | ---------------- | --------- | ----------------------- |
    | "objectUrl"      | Yes       |                         |
    | "title"          | No        | The file's path + title |
    | "clientMetadata" | No        |                         |

    <Note>Keys / Flags that are not required can be omitted from the JSON file entirely.</Note>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
      "text": [
          {
          "objectUrl": "/path/to/my/bucket/website1.html",
          "clientMetadata": {"htmlType": "Single Extension"}
          },
          {
          "objectUrl": "/path/to/my/bucket/website2.html",
          "clientMetadata": {"htmlType": "Raw"}
          }
        ]
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "/path/to/my/bucket/website1.html",
            "clientMetadata": {
              "htmlType": "Single Extension"
            }
          },
          {
            "objectUrl": "/path/to/my/bucket/website2.html",
            "clientMetadata": {
              "htmlType": "Raw"
            }
          }
        ]
      },
      {
        "text": [
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + /path/to/my/bucket/website1.html",
            "clientMetadata": {
              "htmlType": "Single Extension"
            }
          },
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + /path/to/my/bucket/website2.html",
            "clientMetadata": {
              "htmlType": "Raw"
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
          "audio": [
              {
                  "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/websites/htmls/website1.html",
                  "clientMetadata": {"htmlType": "Single Extension"}
              },
              {
                  "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/websites/htmls/website2.html",
                  "clientMetadata": {"htmlType": "Raw"}
              }
          ],
          "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a Folder to Store Your Audio Files">
    All files in Encord must be stored within folders. Therefore, you need to create a folder before registering any data with Encord. To create a folder:

    1. Navigate to **Data** > **Files & Folders**
    2. Click the **+ New folder** button to create a new folder. Select the type of folder you want to create.

    <div>
      <img />
    </div>

    3. Give the folder a meaningful name and description.

    4. Click **Create** to create the folder.
       The folder is listed in **Files & Folders**.
  </Step>

  <Step title="Upload Your Text files to Encord">
    <Warning> To learn how to upload local files [click here](/platform-documentation/Curate/add-files/index-upload-local-data) </Warning>

    <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

    1. Navigate to **Data** > **Files & Folders** in the Encord platform.
    2. Click into a Folder.
    3. Click **+ Upload files**.
       A dialog appears.

    <div>
      <img />
    </div>

    4. Click **Import from cloud data**.

    <div>
      <img />
    </div>

    <Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

    6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.
  </Step>
</Steps>

## STEP 2: Set Up Your Project

<Steps>
  <Step title="Create a Dataset">
    1. Click the **New dataset** button in the *Datasets* section in *Annotate*.

    <div>
      <img />
    </div>

    2. Give your Dataset a meaningful title and description. A clear title and description keeps your data organized.

    <Tip>Toggle  **Looking to create a mirrored dataset?** to create a [Mirrored Dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets#mirrored-datasets). </Tip>

    <div>
      <img />
    </div>

    3. Click **Create dataset** to create the Dataset.

    ### Attach files

    <Tip>[You can add data to Datasets from the **Files & Folders** or the *Datasets* screens](/platform-documentation/Curate/index-files#add-data-to-datasets).</Tip>

    <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

    1. Navigate to the *Datasets* section under the *Annotate* heading.
    2. Click the Dataset you want to attach data to.
    3. Click **+Attach existing files**.

    <div>
      <img />
    </div>

    4. Select the folders containing the files you want to attach to the Dataset. To select individual files, double-click a folder to see its contents, and select the files you want to add to the Dataset.

    5. Click **Attach data** to attach the selected files to the Dataset.
  </Step>

  <Step title="Create an Ontology">
    <Note>We recommend learning about [Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) before creating Ontologies. </Note>

    <Warning>Ensure that Ontologies used for text annotations only include Classifications and *Text Region* objects </Warning>

    1. Click the **New ontology** button in the *Ontologies* section to create a new Ontology.

    <div>
      <img />
    </div>

    2. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.

    3. Click **Next** to continue.

    <div>
      <img />
    </div>

    4. Define your Ontology structure. Text files are labeled using the *Text Region* object type and Classifications.

    **To add a Text Region object**:

    <div>
      <img />
    </div>

    1. Click **+ Add object** to create a new object.
    2. Give the object a name, for example "Region of Interest".
    3. Select the *Text Region* object type.
    4. Optionally, configure the object to add any attributes.
    5. Optionally, enable the **Required** toggle to mark the object as *Required*.
    6. Repeat these steps for as many Text Region objects as necessary.

    **Configure Objects**:

    Objects can be configured to add attributes.

    <div>
      <img />
    </div>

    1. Click the arrow button next to the object to start configuring.
    2. Click **+ Add attribute** to add an attribute.
    3. Select the attribute type: Text, radio button, or checklist.
    4. Give the attribute a name, for example "Why is this region of interest?" could be a text attribute.
    5. If your attribute is a radio button or a checklist click **Add option** and add options.

    <div>
      <img />
    </div>

    6. Optionally mark the object as [*Required*](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#mark-as-required) and / or [*Dynamic*](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes).

    7. Click the **Back to parent** button to return the Ontology creation view.

    **To add a Classification**:

    <div>
      <img />
    </div>

    1. Click **+ Add classification** to create a new classification.
    2. Give the classification a name. For example, "HTML Type".
    3. Optionally, configure the classification to change the classification type. The default classification type is a text field.
    4. Optionally, enable the **Required** toggle to mark the classification as *Required*.
    5. Repeat these steps for as many classifications as necessary.

    **Configure classifications**:

    Classifications can be configured to change the classification type, and to add classification options to radio buttons and check lists.

    1. Click the arrow icon next to an object to configure the classification.

    <div>
      <img />
    </div>

    2. Click the classification type to change the classification type. The default classification type is a text field.
    3. Click **Add option** to add an option if you have selected a radio button or check list classification.
    4. Enter a name for the classification option. For example, the classification "HTML Type" can have the options "Raw", and "Single Extension".
    5. Click the **Back to parent** button to return the Ontology creation view.
  </Step>

  <Step title="Create a Project">
    1. In the Encord platform, navigate to **Projects**.
    2. Click the **+ New annotation project** button to create a new Project.

    <div>
      <img />
    </div>

    3. Give the Project a meaningful title and description.

    <div>
      <img />
    </div>

    <Note>
      If you are part of an [Workspace](/platform-documentation/General/general-workspace-settings), an optional [Project tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags) drop-down is visible. Project tags are useful for categorizing and finding your Projects. Select as many tags as are relevant for your Project.
    </Note>

    4. Click the **Attach ontology** button.

    5. Select the [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) you created previously from the list using the **Select** button.

    <div>
      <img />
    </div>

    6. Click **OK** to attach the Ontology to the Project.

    7. Click the **Attach datasets** button.

    8. Select the [Dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets) you created previously from the list using the **Attach** button.

    <div>
      <img />
    </div>

    9. Click **OK** to attach the Dataset(s) to the Project.

    <div>
      <img />
    </div>

    10. Click the **Load from template** button to use a [Workflow template](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates).

    <div>
      <img />
    </div>

    11. Select the template you want to use and click **Load template**.

    12. Click **Create project** to finish creating the Project.

    <div>
      <img />
    </div>
  </Step>
</Steps>

## STEP 3: Label Your Text Files

### Text

<div>
  <iframe />
</div>

<AccordionGroup>
  <Accordion title="Labeling Text Files">
    <Tip>
      Use `Ctrl+C` (Windows/Linux) or `Cmd+C` (Mac) to copy the selected text to your clipboard. and Use `Ctrl+V` (Windows/Linux) or `Cmd+V` (Mac) to paste.
    </Tip>

    #### Text

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label text files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-text-doc.gif)
  </Accordion>

  <Accordion title="Labeling JSON Files">
    #### JSON

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label JSON files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-json.gif)
  </Accordion>

  <Accordion title="Labeling XML Files">
    #### XML

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label XML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-xml.gif)
  </Accordion>
</AccordionGroup>

### HTML

Encord supports both raw HTML files and single-extension HTML files. The key difference is that single-extension HTML files include all the necessary elements to render the webpage, such as CSS and JavaScript.

<Tip>
  Use `Ctrl+C` (Windows/Linux) or `Cmd+C` (Mac) to copy the selected text to your clipboard. and Use `Ctrl+V` (Windows/Linux) or `Cmd+V` (Mac) to paste.
</Tip>

<div>
  <iframe />
</div>

<AccordionGroup>
  <Accordion title="Labeling HTML - Single Extension">
    #### HTML - Single Extension

    1. Click a *Text Region* label type (or use the hotkey)
    2. Highlight the text you want to apply the label to.

    ![Label HTML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-html-single-extension.gif)
  </Accordion>

  <Accordion title="Labeling HTML - Raw">
    #### HTML - Raw

    1. Click a *Text Region* label type (or use the hotkey)
    2. Highlight the text you want to apply the label to.

    ![Label HTML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-html-raw.gif)
  </Accordion>
</AccordionGroup>

### Using Relation Text Attributes - Text and HTML

Relation text attributes link an object to another object. In images or videos this could be linking a chicken's body to its wing. In PDFs or text documents (text or HTML files) this could be linking words with measurements, or linking words with other words.

<Note>
  Your Ontology must MUST contain text attributes with the Relation feature enabled if you want to use relation text attributes.

  ![Add Relation Text Attribute](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/project-ontologies-text-link.gif)
</Note>

While annotating, you can create a relationship between any object with a relation text attribute and any other object. After you create a relation between objects a workflow arrow points from the object with the relation text attribute to the other object.

![Link objects](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/annotate-project-link-text-region.gif)


# End-to-End Examples
Source: https://docs.encord.com/end-to-end/e2e-landing-page



## Multimodal

<CardGroup>
  <Card title="Human-in-the-Loop Validation" icon="person-walking-arrow-loop-left" href="/end-to-end/Features/e2e-data-groups">
    Humans validating ML predictions using generated output (text file) and videos in a single interface.
  </Card>

  <Card title="PCD" icon="cube" href="/end-to-end/Modalities/pcd/e2e-pcd">
    Annotating Point cloud data (PCD) using Scenes.
  </Card>
</CardGroup>

## Images and Video

<CardGroup>
  <Card title="Single Image Annotation" icon="image" href="/platform-documentation/Annotate/annotate-label-editor/annotate-images">
    Annotating single images in a Project.
  </Card>

  <Card title="Images and Video Annotation" icon="video" href="/end-to-end/Modalities/e2e-data-images-videos">
    Annotating images and videos in a Project.
  </Card>
</CardGroup>

## Audio

<CardGroup>
  <Card title="Transcription" icon="file-audio" href="/platform-documentation/Annotate/annotate-label-editor/annotate-audio">
    Annotating audio data for transcription.
  </Card>

  <Card title="RLHF Audio" icon="file-audio" href="/end-to-end/Modalities/audio/audio-rlhf">
    Reinforcement Learning from Human Feedback (RLHF) with audio data.
  </Card>
</CardGroup>

## Text

<CardGroup>
  <Card title="Text and HTML Annotation" icon="file-lines" href="/end-to-end/Modalities/text/text-annotation">
    Annotating text and HTML data.
  </Card>

  <Card title="Entity Mapping" icon="table" href="/end-to-end/Modalities/tabular/e2e-tabular-data">
    Annotate rows of data in a tabular format.
  </Card>
</CardGroup>


# Project Admins
Source: https://docs.encord.com/persona-admins/admin-project



<span>
  Project Role
</span>

## Project Roles

The table below illustrates the role-based access control for various Project actions available to different user types.

<Note>
  Contact [support](mailto:support@encord.com) to gain access to the Viewer role for your Projects.
</Note>

<Note>
  Viewers on Workflow projects can access the **Explore** tab in read-only mode. They can browse grid, analytics, and embeddings views and apply existing filters, but cannot create or modify collections, filter presets, or prediction sets, and cannot perform bulk actions. Viewers can still post comments and raise issues. The **Explore** tab remains inaccessible for all roles on ManualQA projects.
</Note>

| Permission                                                     | Project Admin | Team Manager            | Reviewer    | Annotator     | Annotator & Reviewer | Viewer        |
| -------------------------------------------------------------- | ------------- | ----------------------- | ----------- | ------------- | -------------------- | ------------- |
| Attach / Detach Datasets                                       | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Attach / Switch Ontology                                       | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Delete                                                         | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Invite team members                                            | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Manage team permissions                                        | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Manage admins                                                  | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Annotate & review tasks                                        | ✅             | ✅                       | Review only | Annotate only | ✅                    | ❌             |
| Confirm annotations                                            | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Control task assignments and status                            | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Exporting labels                                               | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Assign and Release Tasks                                       | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Assign task (per-row, label queue)                             | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Release task (per-row, label queue)                            | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Change task priority (per-row, label queue)                    | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Move task to stage (per-row, label queue)                      | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Browse and inspect labels (all workflow stages)                | ✅             | ✅                       | ✅           | ✅             | ✅                    | ✅             |
| Create and resolve comments                                    | ✅             | ✅                       | ✅           | ✅             | ✅                    | ✅             |
| Access Project Explorer (Explore tab) — Workflow projects only | ✅             | ✅ (statistics fallback) | ❌           | ❌             | ❌                    | ✅ (read-only) |

## Export Labels

Exporting labels is one of the most important tasks a Project Admin performs. You can export labels from a Project at any point in the Project's completeness from any block in the Project Workflow.

<Columns>
  <Card title="Exporting labels" icon="file-code" href="/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels">
    Export your labels from Encord
  </Card>

  <Card title="JSON format" icon="code" href="/platform-documentation/Annotate/annotate-export/annotate-export-json">
    JSON label export format
  </Card>

  <Card title="COCO Format" icon="code" href="/platform-documentation/Annotate/annotate-export/annotate-export-coco">
    COCO label export format
  </Card>

  <Card title="Sync Labels to Cloud Storage" icon="cloud" href="/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels#export-labels-to-cloud-storage-recommended">
    Sync your labels to Cloud Storage
  </Card>
</Columns>

## Explore

Explore allows you to perform label QA, bulk actions, and view data and label analytics in your Project.

### Bulk Actions

<Columns>
  <Card title="Bulk classification" icon="file-code" href="/platform-documentation/Annotate/active-annotate/bulk-actions/annotate-bulk-classify">
    Apply classifications in bulk.
  </Card>

  <Card title="Bulk deletion" icon="code" href="/platform-documentation/Annotate/active-annotate/bulk-actions/annotate-delete-labels">
    Delete labels in bulk
  </Card>

  <Card title="Bulk Edit Class" icon="code" href="/platform-documentation/Annotate/active-annotate/bulk-actions/annotate-edit-object-class">
    Edit object labels in bulk
  </Card>

  <Card title="Bulk Task Prioritization" icon="cloud" href="/platform-documentation/Annotate/active-annotate/bulk-actions/annotate-set-priority">
    Set Task priority in bulk
  </Card>
</Columns>

## Task Management

As a Project Admin, you can manage individual tasks directly from the Label Queue without opening the full task editor. Click the three-dot (**⋯**) menu on any task row to access the following actions:

* **Assign** — Assign the task to a specific project member (available on annotation and review stages).
* **Release** — Unassign the task from its current assignee (available for assigned tasks only).
* **Change priority** — Set a new priority value for the task.
* **Move to stage** — Move the task to another stage in the Project Workflow.

<Note>
  **Assign**, **Release**, **Change priority**, and **Move to stage** are only available to users with the Project Admin or Team Manager role. **View**, **Activity log**, and **API details** are available to all users who can see the queue row.
</Note>

To perform bulk operations on multiple tasks, select the tasks first. The **Actions** button appears in the floating selection toolbar (list and grid views) or in the top action bar (explorer view) once tasks are selected.

For full details on managing tasks in the Label Queue, see the [Label Queue documentation](/platform-documentation/Annotate/annotate-projects/annotate-workflow-queue).

## Project Settings

<Columns>
  <Card title="Project Settings" icon="file-code" href="/platform-documentation/Annotate/annotate-projects/annotate-project-settings">
    Configure Project settings for all users.
  </Card>
</Columns>

## Project Management

<Columns>
  <Card title="Create Projects" icon="file-code" href="/platform-documentation/GettingStarted/gettingstarted-create-project">
    Learn how to create Projects.
  </Card>

  <Card title="Manage Projects" icon="file-code" href="/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects">
    Learn how to manage Projects.
  </Card>

  <Card title="Project Workflows" icon="file-code" href="/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates">
    Learn how to create Project Workflows.
  </Card>
</Columns>


# Workspace Admins
Source: https://docs.encord.com/persona-admins/admin-workspace



<span>
  Workspace Role
</span>

Workspace Admin is a workspace-level role. Workspace Admins are the highest-privilege user role in Encord. As a Workspace Admin, you have complete control of the Encord platform, all data, users, and Projects.

## Get started

<Columns>
  <Card title="Get started" icon="hourglass-start" href="/platform-documentation/GettingStarted/gettingstarted-welcome">
    Getting started with Encord - Workspace Admins
  </Card>
</Columns>

## Access and visibility

You can:

* View and access Workspace Settings and Analytics (other roles cannot).
* View all Projects, Datasets, Ontologies, users, files, folders and integrations in the Workspace.

<Columns>
  <Card title="Workspace Basics" icon="globe" href="/platform-documentation/General/general-workspace-basics">
    Getting started with Encord - Workspace Admins
  </Card>

  <Card title="Workspace settings" icon="gear" href="/platform-documentation/General/general-workspace-settings">
    Workspace users, groups, tags, and activities.
  </Card>

  <Card title="Workspace analytics" icon="chart-line" href="/platform-documentation/General/general-workspace-analytics">
    Workspace overview
  </Card>
</Columns>

## User management

You can:

* Invite users to and remove users from the Workspace.
* Manage Workforce roles.
* Create and manage user groups and assign group managers.

<Columns>
  <Card title="Manage Users" icon="user-gear" href="/platform-documentation/General/general-workspace-settings#users">
    Invite, remove, and manage users.
  </Card>

  <Card title="Manage Groups" icon="user-group" href="/platform-documentation/General/general-workspace-settings#groups">
    Create, remove, and manage Groups.
  </Card>
</Columns>

## Data

You can curate all your data, see all data and folders in Index, and manage folder collaborators.

<Columns>
  <Card title="Setup Data Integrations" icon="hourglass-start" href="/platform-documentation/General/annotate-data-integrations">
    Setup data integrations to get data into Encord.
  </Card>

  <Card title="Data in Encord" icon="file-code" href="/platform-documentation/Curate/index-getting-started">
    Command and Control for your Data.
  </Card>
</Columns>

## Resource creation

You can:

* Create, delete, and edit Projects, Datasets, Ontologies.
* Join any existing Project, Dataset, Ontology in the workspace and automatically become Admin of that resource.

<Columns>
  <Card title="Datasets" icon="folder-tree" href="/platform-documentation/Annotate/annotate-datasets/annotate-datasets">
    Create, delete, and manage Datasets.
  </Card>

  <Card title="Ontologies" icon="https://storage.googleapis.com/docs-media.encord.com/assets/icon-ont-icon.png" href="/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies">
    Understand, create, delete, and manage Ontologies.
  </Card>

  <Card title="Projects" icon="https://storage.googleapis.com/docs-media.encord.com/assets/icon-ont-icon.png" href="/platform-documentation/GettingStarted/gettingstarted-create-project">
    Understand, create, delete, and manage Projects.
  </Card>
</Columns>

## Programmatic actions

Workspace Admins (or users using a Service Account with Admin access), can control Encord programmatically using the Encord SDK.

<Columns>
  <Card title="Workspace-wide actions" icon="file-code" href="/sdk-documentation/general-sdk/sdk-org-actions">
    Workspace-wide actions with the SDK.
  </Card>

  <Card title="Import labels" icon="file-import" href="/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual">
    Import labels using the SDK.
  </Card>

  <Card title="Export labels" icon="file-export" href="/sdk-documentation/sdk-labels/sdk-export">
    Export labels using the SDK.
  </Card>
</Columns>


# Admins
Source: https://docs.encord.com/persona-admins/admins-index



Encord supports the following administrator roles:

* Workspace Admin: Workspace Admins are Workspace-level roles. Workspace Spaces have complete access and control over all parts of the Encord platform.

* Project Admin: Project Admins are Project-level roles. Project Admins have complete access and control over Projects they are a part of.


# Team Managers
Source: https://docs.encord.com/persona-managers/manager-team-manager



<span>
  Project Role
</span>

As a Team Manager, you can:

* Monitor the progress and performance of people who annotate and review Tasks across a Project.
* Monitor Project completeness.
* Monitor Project critical analytics (Tasks, Labels, Issues).
* Act as annotators and reviewers across a Project.
* Export labels from Projects.

## Monitor Task Performance

Use the **Analytics** > **Collaborators** page to monitor the performance of anyone who annotated or reviewed Tasks in the Project.

Metrics for anyone who annotated Tasks are:

* Number of submitted tasks
* Number of skipped tasks
* Number of approved tasks
* Number of rejected tasks
* Task rejection rate
* Number of labels (objects and classifications) created
* Number of labels (objects and classifications) edited
* Number of deleted labels (objects and classifications)
* Number of approved labels (objects and classifications)
* Number of rejected labels (objects and classifications)
* Label rejection rate
* Total annotation time
* Average time per label (objects and classifications)
* Average time per task
* Number of Issues for the person annotating

Metrics for anyone who reviewed Tasks are:

* Number of approved tasks
* Number of rejected tasks
* Task rejection rate
* Number of labels (objects and classifications) created
* Number of labels (objects and classifications) rejected
* Number of deleted labels (objects and classifications)
* Number of approved labels (objects and classifications)
* Number of rejected labels (objects and classifications)
* Total review time
* Average time to review per label
* Average time to review Tasks
* Number of Issues created when reviewing Tasks

## Monitor Project completeness

Use the **Overview** and **Queue** pages to monitor the completeness of the Project.
From those pages you can see the number of Tasks in each stage of the Project.

## Monitor Project critical analytics

Use the **Analytics** > **Tasks**,  **Analytics** > **Labels**, and **Analytics** > **Issues** pages to monitor critical Project metrics.

## Manage Individual Tasks

As a Team Manager, you can manage individual tasks directly from the Label Queue without opening the full task editor. Each task row in the queue has a three-dot (⋯) menu that gives you quick access to the following actions:

* **View** — Open the task in the label editor in view-only mode.
* **Assign** — Assign the task to a specific project member. Available for annotation and review stages only.
* **Release** — Unassign the task from its current assignee. Only available for tasks that are currently assigned.
* **Change priority** — Open a modal to set a new priority value for the task.
* **Move to stage** — Move the task to a different workflow stage. A submenu lists the valid target stages available in the project.

<Note>
  The **Assign**, **Release**, **Change priority**, and **Move to stage** actions are only available to users with the Team Manager or Admin role. The **View**, **Activity log**, and **API details** actions are available to all users who can see the queue row.
</Note>

<Note>
  The **Assign** action is not available for consensus-annotation rows. Assignment for those tasks is handled per-subtask by the workflow coordinator.
</Note>

If an action such as Assign, Release, or Move to stage fails, Encord displays an error notification so you can retry or investigate.

For full details on the Label Queue and bulk task operations, see the [Label Queue documentation](/platform-documentation/Annotate/annotate-projects/annotate-workflow-queue).

## Export Labels

You can export labels from any page within the Project.

You can specify the format the labels export, the stage where the labels reside, and which specific labels to export. You can also create label versions.


# Workforce Managers
Source: https://docs.encord.com/persona-managers/manager-workforce



<span>
  Workspace Role
</span>

As a Workforce Manager, you can:

* Create and manage user groups (for example, “Annotators”, “Reviewers”, "Annotators-Reviewers").
* Add and remove users in the Groups you manage.
* Add other Workforce Managers or Admins as group managers/viewers.

## Add Workforce users

You can add Workforce Managers and Taskers to Encord. Workforce Managers can be made Team Managers in Projects.
Taskers can be added to Groups, and Groups can be added to Projects.

1. Click **Workspace Settings** in the Workspace section.

   The *Users* page appears.

2. Click **Invite users**.

   The *Invite users to workspace* dialog appears.

3. Type the email addresses of the users you want to add.

4. Select one of the following:
   * **Workforce manager**: Access to any resources they have been assigned to, ability to create and manage groups and assign them to resources. For example, Team Managers.

   * **Tasker**: Only given access to the specific resources they have been assigned to. For example, Annotators, Reviewers, and Annotator-Reviewers.

5. Click **Invite**.

## Create Groups

<Note>
  You can add *Members* and *Managers* using a CSV file after creating a Group. Create a Group with only a title and save it, then edit the Group.
</Note>

1. Click **Workspace Settings** in the Workspace section.

   The *Users* page appears.

2. Click **Groups**.

   The *Groups* page appears.

3. Click **Create groups**.

   A dialog box appears with *Add Members*.

4. Click the **Edit** button for the Group's title.

5. Specify a meaningful name for the Group.

6. OPTIONAL: Provide a meaningful description for the Group.

7. Provide the email addresses of the users you want to add to the Group as Taskers.

8. Click **Add**.

9. Click **Next**.

   The *Add Managers* section appears.

10. Provide the email addresses of the users you want to manage Group.

11. Click **Add**.

12. Click **Create group**.

### Edit Groups

1. Click **Workspace Settings** in the Workspace section.

   The *Users* page appears.

2. Click **Groups**.

   The *Groups* page appears.

3. Click **Edit** for the Group you want to edit.

   A settings dialog for the Group appears.

4. Edit the title.

5. Add or remove *Members* and *Managers* manually or using a CSV file.

6. Click **Managers** and change the role.

7. Click the exit dialog button when you are finished editing the Group.

### Delete Group

Deleting a Group, removes the Group from all attached Projects, Datasets, and Ontologies.

<Warning>
  This action cannot be undone.
</Warning>

1. Click **Workspace Settings** in the Workspace section.

   The *Users* page appears.

2. Click **Groups**.

   The *Groups* page appears.

3. Click **Edit** for the Group you want to edit.

   A settings dialog for the Group appears.

4. Click **Delete group**.

   A dialog appears.

5. Type *delete* in the text field.

6. Click **Delete**.

## Add Groups to Projects

Some companies may want Workforce Managers to create the Projects that a workforce works on.
If that is the case, the Workforce Manager must have access to all the resources (Datasets, Ontology, Workflow Template) required for the Project to create the Project.

1. Go to **Annotate** > **Projects**.

2. Select a Project from the Project list.

3. Go to **Settings** > **Team**.

4. Add Groups or Users to the Project, while specifying the Project roles for the Groups or Users.


# Managers
Source: https://docs.encord.com/persona-managers/managers-index



Encord supports the following manager roles:

* Workforce Manager: Workforce Managers are Workspace-level roles. Workforce Managers enable your 3rd-party workforces
  to self-organize without the need for Workspace Admin involvement.

* Team Manager: Team Managers are Project-level roles. Team Managers manage annotators and reviewers on Projects.

<Note>
  Workforce Managers are likely to have the role of Team Manager on Projects.
</Note>


# Automatic Annotation
Source: https://docs.encord.com/persona-taskers/tasker-annotate-auto



Annotators have some choices when it comes to automatically labeling and tracking objects:

* SAM 3: Automatically detect and track one or more objects.
* SAM 2: Automatically detect objects and track one or more objects.
* Interpolation: Tracking objects between a range of frames.
* Agents: Automatically detect and track objects.

## SAM 3

<Warning>
  This feature is currently in Early Access. Its user experience is still under development and may change as improvements are introduced. Contact support to gain access to SAM 3.
</Warning>

SAM 3 allows you to label and track one or more objects in a data unit. You can also use prompts to SAM 3 to help with labeling.

### Label one object

<iframe title="YouTube video player" />

Labeling one object is the same for images and videos.

1. Go to **Annotate** > **Projects**.

2. Click a Project from the Project list.

3. OPTIONAL: Filter the data units as required from the *Queue*.

4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*.

   The *Label Editor* appears.

5. Click the **Toggle auto-annotation** button for the object class from the *Classes* list.

   <Tip>
     Use the keyboard shortcut for the object class then use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>A</kbd>.
   </Tip>

   A dialog appears for SAM 3.

6. Select **Single object**, if it is not selected.

7. Click on an object in your image or video.

<Tip>
  Use the following when needed:

  * **Left click** to *INCLUDE* an area.
  * **Right click** to *EXCLUDE* an area.
</Tip>

8. Click **Save**.

<Tip>
  Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
</Tip>

9. Continue labeling as required.

10. Click **Submit** to submit the task.

### Track one object

You can track objects in videos or image sequences.

<AccordionGroup>
  <Accordion title="Track while creating new labels">
    <iframe title="YouTube video player" />

    1. Go to **Annotate** > **Projects**.

    2. Click a Project from the Project list.

    3. OPTIONAL: Filter the data units as required from the *Queue*.

    4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*. The *Label Editor* appears.

    5. Click the **Toggle auto-annotation** button for the object class from the *Classes* list. A dialog appears for SAM 3.

    <Tip>
      Use the keyboard shortcut for the object class then use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>A</kbd>.
    </Tip>

    6. Select **Single object**, if it is not selected.

    7. Click on an object in your image or video.

    <Tip>
      Use the following when needed:

      * **Left click** to *INCLUDE* an area.
      * **Right click** to *EXCLUDE* an area.
    </Tip>

    8. Specify the number of frames to track the object across.

       <Tip>
         You can specify a global setting for number of frames to track in **Editor Settings** > **Label Tracking** > **Number of frames to predict**.
       </Tip>

    9. Click **Track backwards** or **Track forwards**.

    10. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    11. Continue labeling as required.

    12. Click **Submit** when you are done labeling the task.
  </Accordion>

  <Accordion title="Track on existing labels">
    This task assumes you are already in the Label Editor.

    **Method 1**

    <iframe title="YouTube video player" />

    1. Hover over a label in the Label Editor workspace.

    2. Right click. A menu appears.

    3. Click one of the following:

       * **Track forwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    4. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    5. Continue labeling/tracking objects as required.

    6. Click **Submit** to submit the task.

    **Method 2**

    <iframe title="YouTube video player" />

    1. Hover over a label in the *Labels* list. A small groups of icons appear.

    2. Click the kebab icon. A menu appears.

    3. Click one of the following:

       * **Track forwards from this frame** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards from this frame** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    4. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    5. Continue labeling/tracking objects as required.

    6. Click **Submit** to submit the task.
  </Accordion>
</AccordionGroup>

### Label multiple objects

<iframe title="YouTube video player" />

You can track objects in videos, image groups, or image sequences.

1. Go to **Annotate** > **Projects**.

2. Click a Project from the Project list.

3. OPTIONAL: Filter the data units as required from the *Queue*.

4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*. The *Label Editor* appears.

5. Click the **Detect all** button for the object class from the *Classes* list.

<Note>
  You can also use the keyboard shortcut for the class, then click <kbd>SHIFT</kbd> + <kbd>A</kbd>, and then click **Detect all** > **Detect all objects**.
</Note>

<Tip>
  You can specify a global setting for number of frames to track in **Editor Settings** > **Label Tracking** > **Number of frames to predict**.
</Tip>

6. Click **Save**.

<Tip>
  Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
</Tip>

7. Continue labeling as required.

8. Click **Submit** when you are done labeling the task.

### Use SAM 3 prompt

<iframe title="YouTube video player" />

1. Go to **Annotate** > **Projects**.

2. Click a Project from the Project list.

3. OPTIONAL: Filter the data units as required from the *Queue*.

4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*. The *Label Editor* appears.

5. Click the **Toggle auto-annotation** button for the object class from the *Classes* list. A dialog appears for SAM 3.

<Tip>
  Use the keyboard shortcut for the object class then use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>A</kbd>.
</Tip>

6. Select **Detect all**.

7. Provide a prompt to start labeling.

8. Click on an object in your image or video.

<Tip>
  Use the following when needed:

  * **Left click** to *INCLUDE* an area.
  * **Right click** to *EXCLUDE* an area.
</Tip>

9. Specify the number of frames to track the object across.

   <Tip>
     You can specify a global setting for number of frames to track in **Editor Settings** > **Label Tracking** > **Number of frames to predict**.
   </Tip>

10. Click **Track backwards** or **Track forwards**.

11. Click **Save**.

<Tip>
  Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
</Tip>

12. Continue labeling as required.

13. Click **Submit** when you are done labeling the task.

### Track multiple objects

You can track objects in videos or image sequences.

You can track multiple objects, of multiple classes, at the same time.

<AccordionGroup>
  <Accordion title="Track multiple objects while creating new labels">
    <iframe title="YouTube video player" />

    In this example, we'll label multiple objects at once by class and then track all of them.

    1. Go to **Annotate** > **Projects**.

    2. Click a Project from the Project list.

    3. OPTIONAL: Filter the data units as required from the *Queue*.

    4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*. The *Label Editor* appears.

    5. Click the **Toggle auto-annotation** button for the object class from the *Classes* list. A dialog appears for SAM 3.

    <Tip>
      Use the keyboard shortcut for the object class then use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>A</kbd>.
    </Tip>

    6. Select **Detect all**.

    7. Select the labels you want to track objects on by doing one of the following:

       * Hold down <kbd>SHIFT</kbd> and select the labels to track from the Label Editor workspace or from the *Labels* list
       * Left click and drag the area, in the Label Editor workspace, with the labels you want to track.

    8. Right click. A menu appears.

    9. Click one of the following:

       * **Track forwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

       <Tip>
         You can specify a global setting for number of frames to track in **Editor Settings** > **Label Tracking** > **Number of frames to predict**.
       </Tip>

    10. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    11. Continue labeling and tracking as required.

    12. Click **Submit** when you are done labeling the task.
  </Accordion>

  <Accordion title="Track multiple objects on existing labels">
    This task assumes you are already in the Label Editor.

    **Method 1**

    <iframe title="YouTube video player" />

    1. Select the labels you want to track objects on:

       * Hold down <kbd>SHIFT</kbd> and select the labels to track in the Label Editor workspace.
       * Left click and drag the area, in the Label Editor workspace, with the labels you want to track.

    2. Right click. A menu appears.

    3. Click one of the following:

       * **Track forwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    4. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    5. Continue labeling/tracking objects as required.

    6. Click **Submit** to submit the task.

    **Method 2**

    <iframe title="YouTube video player" />

    1. Hold down <kbd>SHIFT</kbd> and select labels in the *Labels* list.

    2. Move your cursor to the Label Editor workspace.

    3. Right click. A menu appears.

    4. Click one of the following:

       * **Track forwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    5. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    6. Continue labeling/tracking objects as required.

    7. Click **Submit** to submit the task.
  </Accordion>
</AccordionGroup>

## SAM 2

### Label one object

Labeling one object is the same for images and videos.

1. Go to **Annotate** > **Projects**.

2. Click a Project from the Project list.

3. OPTIONAL: Filter the data units as required from the *Queue*.

4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*.

   The *Label Editor* appears.

5. Click the **Toggle auto-annotation** button for the object class from the *Classes* list.

   <Tip>
     Use the keyboard shortcut for the object class then use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>A</kbd>.
   </Tip>

   A dialog appears for SAM 2.

6. Click on an object in your image or video.

<Tip>
  Use the following when needed:

  * **Left click** to *INCLUDE* an area.
  * **Right click** to *EXCLUDE* an area.
</Tip>

7. Click **Save**.

<Tip>
  Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
</Tip>

8. Continue labeling as required.

9. Click **Submit** to submit the task.

### Track one object

You can track objects in videos or image sequences.

<AccordionGroup>
  <Accordion title="Track while creating new labels">
    1. Go to **Annotate** > **Projects**.

    2. Click a Project from the Project list.

    3. OPTIONAL: Filter the data units as required from the *Queue*.

    4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*. The *Label Editor* appears.

    5. Click the **Toggle auto-annotation** button for the object class from the *Classes* list. A dialog appears.

    <Tip>
      Use the keyboard shortcut for the object class then use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>A</kbd>.
    </Tip>

    6. Click on an object in your image or video.

    <Tip>
      Use the following when needed:

      * **Left click** to *INCLUDE* an area.
      * **Right click** to *EXCLUDE* an area.
    </Tip>

    7. Specify the number of frames to track the object across.

       <Tip>
         You can specify a global setting for number of frames to track in **Editor Settings** > **Label Tracking** > **Number of frames to predict**.
       </Tip>

    8. Click **Track backwards** or **Track forwards**.

    9. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    10. Continue labeling as required.

    11. Click **Submit** when you are done labeling the task.
  </Accordion>

  <Accordion title="Track on existing labels">
    This task assumes you are already in the Label Editor.

    **Method 1**

    1. Hover over a label in the Label Editor workspace.

    2. Right click. A menu appears.

    3. Click one of the following:

       * **Track forwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    4. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    5. Continue labeling/tracking objects as required.

    6. Click **Submit** to submit the task.

    **Method 2**

    1. Hover over a label in the *Labels* list. A small groups of icons appear.

    2. Click the kebab icon. A menu appears.

    3. Click one of the following:

       * **Track forwards from this frame** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards from this frame** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    4. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    5. Continue labeling/tracking objects as required.

    6. Click **Submit** to submit the task.
  </Accordion>
</AccordionGroup>

### Track multiple objects

You can track objects in videos or image sequences.

You can track multiple objects, of multiple classes, at the same time.

<AccordionGroup>
  <Accordion title="Track multiple objects while creating new labels">
    In this example, we'll label multiple objects, and then track all of them.

    1. Go to **Annotate** > **Projects**.

    2. Click a Project from the Project list.

    3. OPTIONAL: Filter the data units as required from the *Queue*.

    4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*. The *Label Editor* appears.

    5. Click the **Toggle auto-annotation** button for the object class from the *Classes* list. A dialog appears.

    <Tip>
      Use the keyboard shortcut for the object class then use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>A</kbd>.
    </Tip>

    6. Create and edit some object labels.

    7. Select the labels you want to track objects on by doing one of the following:

       * Hold down <kbd>SHIFT</kbd> and select the labels to track from the Label Editor workspace or from the *Labels* list
       * Left click and drag the area, in the Label Editor workspace, with the labels you want to track.

    8. Right click. A menu appears.

    9. Click one of the following:

       * **Track forwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    <Tip>
      You can specify a global setting for number of frames to track in **Editor Settings** > **Label Tracking** > **Number of frames to predict**.
    </Tip>

    10. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    11. Continue labeling and tracking as required.

    12. Click **Submit** when you are done labeling the task.
  </Accordion>

  <Accordion title="Track multiple objects on existing labels">
    This task assumes you are already in the Label Editor.

    **Method 1**

    1. Select the labels you want to track objects on:

    * Hold down <kbd>SHIFT</kbd> and select the labels to track in the Label Editor workspace.
    * Left click and drag the area, in the Label Editor workspace, with the labels you want to track.

    2. Right click. A menu appears.

    3. Click one of the following:

       * **Track forwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    4. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    5. Continue labeling/tracking objects as required.

    6. Click **Submit** to submit the task.

    **Method 2**

    1. Hold down <kbd>SHIFT</kbd> and select labels in the *Labels* list.

    2. Move your cursor to the Label Editor workspace.

    3. Right click. A menu appears.

    4. Click one of the following:

       * **Track forwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>T</kbd>.
       * **Track backwards** or use the keyboard shortcut <kbd>SHIFT</kbd> + <kbd>OPTION/ALT</kbd> + <kbd>T</kbd>.

    5. Click **Save**.

    <Tip>
      Use the keyboard shortcut <kbd>ENTER</kbd> or middle click to save.
    </Tip>

    6. Continue labeling/tracking objects as required.

    7. Click **Submit** to submit the task.
  </Accordion>
</AccordionGroup>

## Interpolation

Use interpolation to automatically create labels by estimating the location that labels should be created, between a start frame and an end frame.

<iframe title="YouTube video player" />

1. Go to **Annotate** > **Projects**.

2. Click a Project from the Project list.

3. OPTIONAL: Filter the data units as required from the *Queue*.

4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*. The *Label Editor* appears.

5. Create a label, for an object, on a *start* frame.

6. Move forward in the data unit to the location of the *end* frame.

7. Click **Instantiate object in frame** for the object from the *Labels* list.

8. Do one of the following to interpolate/track between the start and end frames:

   * Right click the label and click **Interpolate** from the menu.
   * Click the kebab icon for the label in the *Labels* list and click **Interpolate**.
   * Use the shortcut <kbd>SHIFT</kbd> + <kbd>I</kbd>.

9 . Edit the created labels as needed.

10. Continue creating and editing labels.

11. Click **Submit**.

### Re-Interpolate

Interpolation results can be improved by manually correcting some interpolated labels, and re-running the interpolation.

Enable the *Interpolation auto adjustments* toggle in the *Drawing settings* section of the label editor settings. This ensures that only labels with a [confidence score (α)](/platform-documentation/Annotate/annotate-label-editor#confidence-score) less than 100% are overwritten in successive interpolations, while manual labels (α = 100%) are kept and serve as key frames.

<div>
  <img />
</div>

***

<div>
  <img />
</div>

This process can be repeated any number of times.

<Note>All labels created using interpolation are always assigned α = 99%.</Note>

## Agents

Your Workspace/Project Admin communicates that they configured an Editor Agent to perform annotation on tasks in the *Queue*. You trigger the Editor Agent from inside the Label Editor.

<iframe title="YouTube video player" />

1. Go to **Annotate** > **Projects**.

2. Click a Project from the Project list.

3. OPTIONAL: Filter the data units as required from the *Queue*.

4. Click **Start task**, **Initiate**, or use the keyboard shortcut <kbd>Command</kbd> + <kbd>Enter</kbd> in the *Queue*. The *Label Editor* appears.

5. Move the cursor to the Label Editor workspace.

6. Right click. A menu appears.

7. Hover over **Trigger agent**. A menu appears.

8. Click the Agent you want to trigger.

9. Edit the labels as required.

10. Click **Submit**.


# Modality Specific Annotation
Source: https://docs.encord.com/persona-taskers/tasker-annotate-manual



## Intro

Adding labels, using the Label Editor, to data units follows the same basic process for all types of data units (a file or group of files).

1. Select a task from the *Queue*.

   The Label Editor opens with the data unit (a file or group of files) in the workspace.

2. Read the **Annotation instructions** for the task, if there are any.

3. Select a label type, from the *Classes* list, using the cursor or keyboard shortcuts.

4. Label the data unit in the Label Editor workspace.

5. Submit the task for review.

Each modality (type of data) have classes (object or classification) that you can use to label the data units in a Project. Depending on the modality, how you label a data unit can change. For example, you can label images and videos with things like bounding boxes, polygons, or bitmasks and classifications. For audio files, you can use audio regions and classifications.

## Best Practices

The fastest way to label data units is by using automatic labeling features (like SAM 3 or Agents). Learn more about automatic labeling [here](/persona-taskers/tasker-annotate-auto).

## Label Editor Settings

Use Label Editor Settings to optimize your labeling experience for each Project or task. For example, using **Turbo mode** allows you to navigate through one class instance at a time Turbo mode hides all other object labels except the label being viewed. This is useful if a class has a large number of attributes, or if there is a large number of object instances.

## Images

When labeling objects on images, we recommend using keyboard shortcuts as much as possible. It speeds up your ability add labels to a data unit.

Right click on labels to display options for the label. For example, from the menu you can copy labels. You can also discover the shortcuts for the actions you can perform on the labels.

<iframe title="YouTube video player" />

## Videos and Image Sequences

Use the Timeline to view the object labels and classifications across the data unit. You can also use the Timeline to add classifications directly to a range of frames in a data unit.

<iframe title="YouTube video player" />

## Audio

Use the Timeline to view and create classifications across the data unit.

<iframe title="YouTube video player" />

## Documents

Use the shortcut <kbd>CONTROL</kbd> + <kbd>SHIFT</kbd> + <kbd>O</kbd> to turn the *Show text outlines* feature on and off.

<iframe title="YouTube video player" />

## Text and HTML

The **Show text annotations** pane is not available for HTML files.

<iframe title="YouTube video player" />

## Point Cloud Data

You annotate from the PCD workspace or from the 2D view of the Scene.

Use **Interpolate** to automatically track objects through Scenes.

For a full list of all settings and options, go [here](/platform-documentation/Annotate/annotate-label-editor/annotate-pcd#editor-actions)

<iframe title="YouTube video player" />

## Medical Images

For a full list of information on annotating medical images go here:

* [DICOM basics](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom)
* [Mammography](/platform-documentation/Annotate/annotate-label-editor/annotate-mammo)

<div>
  <iframe />
</div>

## Multi-Modal

Adding labels or classifications to multi-modal tasks (tasks with different types of data units) simply follows the process outlined in the other sections of this article.


# Issues
Source: https://docs.encord.com/persona-taskers/tasker-annotate-review-issues



## Issues in Tasks

Both Annotators and Reviewers can add Issue threads to Tasks. Typically a thread is started by a Reviewer because of an issue on a Task, but Annotators can start threads too.

<iframe title="YouTube video player" />

**To start an Issue thread:**

1. Click the **Issues** button in the Label Editor.

   A dialog appears.

2. Click the **New issue** button.

3. Specify the location of the Issue.

   You have a few options depending on the data unit you are working on:

   * **Entire file:** The Issue applies to the entire file.
   * **Pin on canvas:** The Issue applies at a specific location of the data unit.
   * **Pin on frame:** The Issue applies on a specific frame in a video.

4. Specify an Issue tag for the Issue thread if your Admin has created Issue tags in Encord.

<Note>
  When your Admin has created Issue tags, the Issues filter panel in the Label Editor includes two tag filter sections:

  * **Including issue tags** — selecting one or more tags shows only issues that carry those tags.
  * **Excluding issue tags** — selecting one or more tags hides issues that carry those tags.

  Both filters compose: an issue must match the include filter AND not match the exclude filter to appear in the list. A tag selected in one section is automatically removed from the options in the other section, so the same tag cannot be both included and excluded at the same time. Clearing all filters resets both sections.
</Note>

5. Type the message you want to communicate in the **Comment** field.

6. Click **Create issue**.

7. Rinse and repeat until you are finished.

## Resolve Issue Threads

Annotators, Reviewers, Annotator-Reviewers, Team Managers, and Project Admins can resolve an Issue thread. There is no mechanism that requires specific Project roles or users to resolve an Issue thread.

<Note>
  To verify if an issue has been resolved, filter the Issue threads. Specify **Resolved** or **All** to view Issue threads that are marked as resolved.
</Note>

<iframe title="YouTube video player" />

**To resolve/close an Issue thread:**

1. Click the **Issues** button in the Label Editor.

   A dialog appears.

2. Click the **Resolve issue** button.

## Delete Issues

Only Project Admins or the person who started the Issue thread, can delete the thread.

<iframe title="YouTube video player" />

**Delete an Issue thread:**

1. Click the **Issues** button in the Label Editor.

   A dialog appears.

2. Click the kebab icon, on the top right of an Issue thread.

3. Click **Delete thread**.


# Annotator Label Editor Basics
Source: https://docs.encord.com/persona-taskers/tasker-label-editor-annotator



<Info>To ensure seamless data loading in Encord, allowlist [https://app.encord.com/](https://app.encord.com/) or [https://app.us.encord.com/](https://app.us.encord.com/) in any 3rd party VPNs, firewalls, or URL isolators. This helps to prevent potential issues with opening your data in Encord.</Info>

This documentation provides a comprehensive guide to using the Label Editor for annotation, covering its components, features, and the display of various elements.

For information on how to label, see our [documentation here](/platform-documentation/GettingStarted/gettingstarted-labeling).

## Annotation Mode

### Introductory Video Tutorials

The following video goes through the basics of annotating visual data in the Label Editor.

<div>
  <iframe />
</div>

<Tip>Check out our [Video Tutorials page](/platform-documentation/General/video-tutorials) for more introductory videos!</Tip>

***

<div>
  <img />
</div>

**Annotation mode components**:

* **A**. [Editor menu](#editor-menu)
* **B**. [Quick toolbar](#quick-toolbar)
* **C**. [Classes](#classes)
* **D**. [Instances and Frame labels](#instances-and-frame-labels)
* **E**. [Automated labeling](#automated-labeling)
* **F**. [Editor timeline (for videos and image sequences only)](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#editor-timeline)
* **G**. Annotation canvas: displays the media asset and provides interface for drawing and editing labels.
* **H**. [Editor header](#editor-header)
* **I**. [Skip or Submit](#skip-or-submit-labels)

***

### Copy / Paste Labels & Instances

Using the copy and paste features in the Label Editor can significantly save time and effort. Here's how you can efficiently use these features:

* **Copy**: To copy both the label and the instance, use the keyboard shortcut <kbd>CMD</kbd> + <kbd>C</kbd> on Mac or <kbd>Ctrl</kbd> + <kbd>C</kbd> on Windows.

* **Paste instance**: To paste the copied instance, use <kbd>CMD</kbd> + <kbd>V</kbd> on Mac or <kbd>Ctrl</kbd> + <kbd>V</kbd> on Windows. Instances can only be pasted onto a different frame from where they were copied.

* **Paste Label**: To paste just the label / shape, use <kbd>CMD</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> on Mac or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> on Windows. Labels can be pasted onto any frame.

* **Clear Cuboid**: To clear a copied 3D cuboid, use <kbd>CMD</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd> on Mac or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd> on Windows with nothing selected.

***

### Bulk Label Operations

Fixing incorrect labels is an important step in producing high-quality datasets. With bulk label operations, annotators can merge labels which should really be one instance, or efficiently delete multiple labels in bulk.

Bulk label operations are accessed in the [editor menu](#editor-menu).

**Merge operations**

Merge one or more label objects into a single object.

1. Select all objects to be merged in the *Select objects to be merged* drop-down menu.
2. Select the target object in the *Select objects to be merged into* field.
3. Click **Merge**.

<div>
  <img alt="Merge objects into a single object" title="merge-operations" />
</div>

**Delete operations**

Encord lets you perform bulk delete operations as follows:

<div>
  <img alt="delete labels in bulk" title="Delete-operations" />
</div>

**Remove labels of a specific class**:

1. Select a class to delete from the *Select class menu*.
2. Specify the frame range.
3. Click the **Delete** button.

**Delete all labels within a frame range**:

1. Navigate to the *Delete all labels from range* section.
2. Set a range to delete labels from.
3. Click **Delete**.

**Delete labels below a specified confidence level**:

1. Navigate to the *Delete labels below confidence* section.
2. Set the minimum confidence threshold. All labels with a [confidence value](#confidence-score) below this threshold are deleted.
3. Specify a range of frames to delete the specified labels from.
4. Click **Delete**.

***

### Classes

In annotation mode, the *Classes* section of the Label Editor shows you the available Ontology classes, both objects and classifications. You can create a new instance by either clicking the desired class, or by using the indicated instantiation hotkeys. Learn more about Ontologies in general [here](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) or learn more about the details of [Ontology structure on Encord](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#ontology-structure).

***

### Instances and Frame labels

The canvas is your labeling area to annotate the *instances* of the Ontology classes.

* An instance is a specific occurrence of a class. For example, if you have a class called "Car", an instance of this class could be "Car(0)", which might represent a specific black sedan. This single instance can appear in a single frame or a range of frames, and therefore, instances may contain multiple labels across frames. You can think of an instance as a unique object that belongs to a certain class.

* A frame label is a frame-specific annotation of an instance. For example, the annotation of "Car(0)" on frame 201 is a label. Labels are used to annotate instances in specific frames, providing more detailed information about the instance in the context of that frame.

<Tip>You can group instances of the same class together using the *Group by class* button.</Tip>

***

### Skip or Submit labels

**Submit tasks**

Labels are applied in the Label Editor. Click the **Submit** button to submit your labels for review.

<div>
  <img />
</div>

**Skip tasks**

Users have the option to skip tasks in cases where, for example, the file is blurred, or if they suspect the task was erroneously added.

<Info>
  Skipping a task automatically creates an [Issue](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#issues-and-comments) and is therefore counted in the [Issue Analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues).
</Info>

When a user skips a task, it is automatically unassigned from them, and the task's status is updated to *Skipped*. If another task is available, it automatically opens in the Label Editor and is assigned to the user.

1. Click the **Skip** button to skip an annotation task.

<div>
  <img />
</div>

2. A dialog appears. Enter a reason for skipping the task - the reason is added as an [issue](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments) to the task that annotators and reviewers can see. If no reason is entered "This task was skipped" is added by default.

<div>
  <img />
</div>

***

### Turbo mode

Turbo mode simplifies the standard annotation workflow, enabling annotators to rapidly assign or confirm attributes. Activate turbo mode and choose an instance from the top-left dropdown menu to set the instance and its relevant attributes.

<Tip>In turbo mode, the auto-zoom feature automatically focuses the point of view on the active instance as you browse through them. You can adjust the zoom manually to get a better view of the instance's context. The view auto-zooms again when moving to another instance.</Tip>

**Enable turbo mode:**

1. Open the [editor settings](#editor-settings).
2. Use the search bar to search for *Turbo mode*.
3. Enable the *Turbo mode* toggle.

***

### View Annotator Instructions

The **Annotator instructions** button is available in the top-left corner of the Label Editor if annotation instructions are provided by the Admin or Team Manager.

<Tip> To learn how to upload annotation instructions click [here](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#upload-annotation-instructions)</Tip>

<div>
  <img />
</div>

***

### Confidence Score

Each instance or label is assigned a confidence score (denoted with the symbol α) that appears next to the label name.

The confidence score is a measure of a machine learning model's certainty that a given prediction is accurate. The higher the confidence score, the more certain a model is about its prediction.

Manual labels are always assigned α = 100%, while label predictions created using models and automated methods such as interpolation have a confidence score below 100% (α \< 100%).

***

### Labels pane

The *Labels* pane shows all the instantiated objects and classifications for a data unit. Objects are grouped first by class, and sorted by creation time within each class, with earlier objects on top. They are named in an "ABC (0)" format, where ABC is the Ontology class and 0 is the first instance annotation.

<div>
  <img />
</div>

* **A**: Toggle between showing displaying all labels, or only labels in the current frame.
* **B**: Show / Hide details for this instance.
* **C**: The range of frames the instances appears on.
* **D**: Attributes the object has and the frames they appear on.
* **E**: Filter by frame range.
* **F**: Sort label instances.
* **G**: Search for an instance.
* **H**: Show / Hide labels.
* **I**: Show / Hide labels for this instance.
* **J**: Additional actions. Described below.
* **K**: Keyboard shortcut to create a label for this instance.
* **L**:[Edit attributes](#attributes) for this instance.
* **M**: Add a new label for this instance.
* **N**: Toggle auto-annotation for [SAM](/platform-documentation/Annotate/automated-labeling/annotate-sam).

**Click the *three dots* icon to access additional actions:**

<div>
  <img />
</div>

**Copy URL**: Copies the URL for the particular object.

**Copy identifier**: Each object instance is automatically assigned a unique alphanumeric ID, which can be used to identify it within the project. This ID is sometimes known alternately as a *feature hash*, *instance hash*, or *instance identifier*. For objects and classifications, it may also be known as the *object hash* or *classification hash*. Use this button to copy the *instance identifier* to your clipboard -- which may help in workflows using specific instances in source code or for other purposes.

**Track from this frame**: Initiates single object tracking using SAM 2. This type of automated labeling creates labels for the specified object from the current frame, according to the [Single object tracking settings](#single-object-tracking-settings) section in the [editor settings](#editor-settings).

**Interpolate**: Interpolates this object's location for a range between specified frames. See our [documentation on interpolation](/platform-documentation/Annotate/automated-labeling/annotate-interpolation) for more details.

**Go to object**: Navigate to the specified object in the data asset. If it is present in more than one frame, the first frame the object appears is shown.

**Split object track**: In some cases, particularly when many objects overlap, labels may be associated with the correct instance in several frames, but later become associated with a different instance. In those cases, use the *Split object track* feature, which will split the labels from one instance into two at the frame specified.

<div>
  <img />
</div>

**Change class**: Use the drop-down in the modal to change the current class of an instance. You can only switch within classes of the same [annotation type](/platform-documentation/Annotate/annotate-ontologies#objects). For example, you cannot switch from a bounding box to a polygon.

<Tip>
  You can select multiple labels and bulk-change their classes by right-clicking and choosing **Change Class**.
</Tip>

**Delete object**: Delete an object from a single frame or a range of frames. To delete labels between frame ranges, move the frame slider to the desired frames, or input the *From* and *To* (exclusive) values in the relevant form.

### Attributes

The details pane allows you to modify attributes efficiently. For [dynamic attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes), use the 'Preserve chosen state' feature. When this feature is toggled 'ON', any subsequent labels for that instance automatically inherit the same dynamic attribute value as the frame where 'Preserve chosen state' was enabled.

#### Propagate Across Gaps

When you annotate objects that appear only on disjointed frame ranges (for example, an object present on frames 0–10, 20–30, and 40–50), setting a dynamic attribute value normally applies only to the contiguous sub-range containing the current playhead position. The **Propagate across gaps** setting extends this behavior so that the value automatically covers all later occurrences of the object.

<Note>**Propagate across gaps** is off by default. When **Limit to a single frame** is also enabled, it takes precedence and **Propagate across gaps** has no effect.</Note>

**To enable Propagate across gaps:**

1. Open the Timeline settings menu in the video Label Editor.
2. Navigate to the **Dynamic attributes** section.
3. Enable the **Propagate across gaps** toggle.

Once enabled, setting a dynamic attribute at the playhead propagates the value forward through all later sub-ranges of the object, stopping only at the next deliberately-set keyframe for that attribute. For checklist attributes, each option propagates independently — only keyframes for the same checklist option stop propagation of that option.

<Tip>See our [tutorial on adding attributes](/platform-documentation/GettingStarted/gettingstarted-labeling#adding-attributes) for a detailed guide</Tip>

If you have numerous attributes, use the search bar to quickly find specific attributes or attribute values.

<div>
  <img />
</div>

***

### Editor Timeline

<Note>
  The Editor Timeline is only available for videos, image sequences, PCD scenes, and audio files.
</Note>

Double-clicking a range on the timeline plays the corresponding section of the video, scene, or audio file.

#### Bulk Actions

Labels and ranges can be multi selected on the timeline using <kbd>Shift</kbd> + click. Selected regions are shown in the left side of the editor.

<div>
  <img />
</div>

The following actions can be performed:

* **Merge ranges**: Merge the selected ranges into a single range.
* **Play range(s)**: Selecting a range allows you to play the file for just that range. If multiple ranges are selected, the file will play for all of the selected ranges in chronological order.
* **Change class**: Change the class for all labels within the selected range(s).

***

### Automated Labeling

Automated labeling includes several techniques to quickly create labels automatically.

* [Interpolation](/platform-documentation/Annotate/automated-labeling/annotate-interpolation) do not require set up or training, and are always available.
* [SAM 2 Segmentation](/platform-documentation/Annotate/automated-labeling/annotate-sam) creates labels by clicking parts of your frame or image.
* [SAM 2 tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam#sam-2-tracking) tracks objects across a range of frames using the \[SAM 2] model.

1. Click the **Automated labeling** button to open the *Automated labeling* panel.
2. Select the type of automated labeling you want to use.
3. Run automated labeling for the selected objects.

***

### Edit Polygons and Polylines

Encord provides multiple tools to edit polygon and polyline labels after they have been created. See our tutorial video for an quick introduction on working with polygons in Encord.

<AccordionGroup>
  <Accordion title="Watch a tutorial for working with polygons">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Move Vertex">
    **To move vertices**:

    Click and drag a vertex to move it to a new location.
  </Accordion>

  <Accordion title="Add Vertex">
    **To add a vertex**:

    You can add more vertices to a polygon after it has been created.

    1. Click the polygon you want to add a vertex to
    2. Click the position along the edge of the polygon you want to add a vertex. Repeat to add as many vertices as necessary.
  </Accordion>

  <Accordion title="Remove Vertex">
    **To remove a vertex**:

    You can remove the last vertex by pressing the <kbd>Backspace</kbd> key while still in *draw* mode.

    1. Click the polygon you want to remove vertices from
    2. Right-click a vertex to delete it
  </Accordion>

  <Accordion title="Extension Tool">
    Use the polygon freehand tool to modify the edge of a polygon or polyline in a free-hand manner and create complex polygons.

    **To use the freehand tool**:

    1. Right-click the polygon you would like to edit.
    2. Click **Edit with brush** or press the <kbd>J</kbd> hotkey.
       A floating brush tool menu appears.
    3. Adjust the brush size to suit your needs.
    4. Mouse over location you would like to start editing from, and click and hold to start the edit process.
    5. Drag the cursor freely to draw out the new polygon edge let go of mouse to finish editing.
  </Accordion>

  <Accordion title="Eraser Tool">
    Use the eraser tool to remove any part of a polygon in a free-hand manner.

    <div>
      <img />
    </div>

    **To use the eraser tool**:

    1. Right-click the polygon you would like to edit.
    2. Click **Edit with brush** or press the <kbd>G</kbd> hotkey.
       A floating brush tool menu appears.
    3. Select the eraser tool.
    4. Adjust the brush size to suit your needs.
    5. Mouse over location you would like to start editing from, and click and hold to start the edit process.
    6. Drag the cursor freely to draw out the new polygon edge let go of mouse to finish editing.
  </Accordion>

  <Accordion title="Merge Polygons">
    Merging polygons combines two polygons into a single polygon

    **To merge Polygons**:

    1. Right-click the polygon you would like to edit.
    2. Click **Merge with another polygon**.
    3. Click the polygon you want to merge with.

    The polygons have been merged.
  </Accordion>

  <Accordion title="Subtract Polygons">
    Subtracting polygons removes the area one polygon from that of another.

    **To subtract polygons**:

    1. Right-click the polygon you would like to edit.
    2. Click **Subtract another polygon**.
    3. Click the polygon you want to subtract from your selected polygon.

    The part of the second polygon that intersected the first is now removed from the first polygon.
  </Accordion>

  <Accordion title="Polygon Brush">
    The Polygon brush allows you to create polygons in the same manner that bitmasks can be created with the brush tool.

    **To create polygons with the brush:**

    1. Click the polygon object from the left pane.
       The polygon tool dialog appears.
    2. Press <kdb>F</kdb> or click the **Brush** icon.
    3. Adjust the size and shape of the brush.
    4. Draw the polygon you need on the data unit in the Label Editor.
    5. Press <kdb>ENTER</kdb> to complete the polygon.
  </Accordion>

  <Accordion title="Freehand Edge Touchup">
    Freehand edge touchup lets you refine a polygon by drawing a new edge between two vertices to adjust and close its shape.

    <div>
      <img />
    </div>

    **To use freehand edge touchup**:

    1. Right-click the polygon you want to edit.
    2. Select **Freehand edge touchup** or press the <kbd>F</kbd> hotkey.
    3. Click the starting vertex for your new edge.
    4. Move the cursor to the target vertex where you want to close the shape.
    5. Click to finalize the edit.
  </Accordion>
</AccordionGroup>

### Editor Canvas Interactions

**Shape-specific interactions**:

| Shape    | Interactions                                                                                          | Modalities                                   |
| -------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Bitmask  | Ability to move (one or multiple)                                                                     | Video / Image Group / Image Sequence / DICOM |
|          | Ability to ‘select multiple’ with <kbd>Shift</kbd> + click                                            | Video / Image Group / Image Sequence / DICOM |
|          | Draw using polygon ‘pen’                                                                              | Video / Image Group / Image Sequence / DICOM |
|          | [Panoptic mode](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#panoptic-mode) | Video / Image Group / Image Sequence / DICOM |
| Polygon  |                                                                                                       | Video / Image Group / Image Sequence / DICOM |
|          | Add vertex with left-click                                                                            | Video / Image Group / Image Sequence / DICOM |
|          | Remove vertex with right-click                                                                        | Video / Image Group / Image Sequence / DICOM |
|          | Use the Brush tool by pressing <kbd>F</kbd>                                                           | Video / Image Group / Image Sequence / DICOM |
| Polyline |                                                                                                       | Video / Image Group / Image Sequence / DICOM |
|          | Add vertex with left-click                                                                            | Video / Image Group / Image Sequence / DICOM |
|          | Remove vertex with right-click                                                                        | Video / Image Group / Image Sequence / DICOM |

**Right-click interactions**:

| Shape                  | Right-click Interactions        | Modalities                                     |
| ---------------------- | ------------------------------- | ---------------------------------------------- |
| Bounding Box           | Track from this frame           | Videos, image groups, and image sequences only |
| Bounding Box           | Interpolate                     | Videos, image groups, and image sequences only |
| Bounding Box           | Split object track              | All                                            |
| Bounding Box           | Change class                    | All                                            |
| Bounding Box           | Copy identifier                 | All                                            |
| Bounding Box           | Delete object                   | All                                            |
| Bounding Box           | Copy URL                        | All                                            |
| Rotatable Bounding Box | Track from this frame           | Videos, image groups, and image sequences only |
| Rotatable Bounding Box | Interpolate                     | Videos, image groups, and image sequences only |
| Rotatable Bounding Box | Split object track              | All                                            |
| Rotatable Bounding Box | Change class                    | All                                            |
| Rotatable Bounding Box | Copy identifier                 | All                                            |
| Rotatable Bounding Box | Delete object                   | All                                            |
| Rotatable Bounding Box | Copy URL                        | All                                            |
| Polygon                | Interpolate                     | All                                            |
| Polygon                | Split object track              | All                                            |
| Polygon                | Change class                    | All                                            |
| Polygon                | Copy identifier                 | All                                            |
| Polygon                | Delete object                   | All                                            |
| Polygon                | Copy URL                        | All                                            |
| Polygon                | Track from this frame           | Videos                                         |
| Polygon                | Edit with brush                 | All                                            |
| Polygon                | Freehand edge touchup           | All                                            |
| Polygon                | Merge with another polygon      | All                                            |
| Polygon                | Subtract another polygon        | All                                            |
| Polyline               | Track from this frame           | Videos, image groups, and image sequences only |
| Polyline               | Interpolate                     | Videos, image groups, and image sequences only |
| Polyline               | Split object track              | All                                            |
| Polyline               | Change class                    | All                                            |
| Polyline               | Copy identifier                 | All                                            |
| Polyline               | Delete object                   | All                                            |
| Polyline               | Copy URL                        | All                                            |
| Polyline               | Freehand edge touchup           | All                                            |
| Keypoint               | Track from this frame           | Videos, image groups, and image sequences only |
| Keypoint               | Interpolate                     | Videos, image groups, and image sequences only |
| Keypoint               | Split object track              | All                                            |
| Keypoint               | Change class                    | All                                            |
| Keypoint               | Copy identifier                 | All                                            |
| Keypoint               | Delete object                   | All                                            |
| Keypoint               | Copy URL                        | All                                            |
| Bitmask                | Interpolate                     | Videos, image groups, and image sequences only |
| Bitmask                | Change class                    | All                                            |
| Bitmask                | Copy identifier                 | All                                            |
| Bitmask                | Delete object                   | All                                            |
| Bitmask                | Copy URL                        | All                                            |
| Bitmask                | Select more bitmasks to combine | All                                            |
| Bitmask                | Download bitmask as image       | All                                            |
| Bitmask                | Track from this frame           | Videos                                         |
| Object Primitive       | Track from this frame           | Videos, image groups, and image sequences only |
| Object Primitive       | Interpolate                     | Videos, image groups, and image sequences only |
| Object Primitive       | Change class                    | All                                            |
| Object Primitive       | Copy identifier                 | All                                            |
| Object Primitive       | Delete object                   | All                                            |
| Object Primitive       | Copy URL                        | All                                            |

***

## Multi-Select Panel

When you select multiple annotations in the Label Editor, a specialized multi-select panel appears in the left sidebar. This panel provides a streamlined interface for managing multiple selected objects and classifications simultaneously.

### Overview

The multi-select panel displays when you have two or more annotations selected and offers:

* A count of selected items displayed in a pill badge
* A list of all selected objects and classifications with their names
* Individual deselection controls for each item
* Bulk actions that can be applied to all selected annotations

### Using the Multi-Select Panel

<Steps>
  <Step title="Select multiple annotations">
    Hold **Shift** and click on multiple objects or classifications in the canvas or labels pane to select them.
  </Step>

  <Step title="View selected items">
    The multi-select panel automatically appears in the left sidebar, showing the count of selected items and listing each annotation by name.
  </Step>

  <Step title="Deselect individual items">
    Click the **X** button next to any annotation name to remove it from the selection.
  </Step>

  <Step title="Apply bulk actions">
    Use the available bulk actions to perform operations on all selected annotations at once.
  </Step>
</Steps>

<Note>The multi-select panel is available for both objects (bounding boxes, polygons, etc.) and classifications, allowing you to work with mixed selections efficiently.</Note>

### Multi-Select Panel Features

**Selected item display**: Each selected annotation appears as a row showing:

* The annotation name and type
* Frame range information where the annotation appears
* A close button to deselect individual items

**Bulk operations**: When multiple items are selected, you can perform actions like:

* Bulk deletion
* Class changes
* Attribute modifications

<Tip>The multi-select panel makes it easy to manage complex annotations by providing a clear overview of your current selection and quick access to bulk editing tools.</Tip>

## Label Branches

Label branches let you keep multiple versions of a Project's labels side-by-side. Use them to preserve a labeled state before a re-labeling pass, run an experiment without disturbing `main`, or hold a reviewer-only copy of labels.

<a href="https://www.loom.com/embed/795d49df662946d0b85bad2adc57ae2a" aria-label="Watch: Create & Display label branches" />

### Create Label Branches

Label branches are created in the [Label Checkpoint Workflow stage](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#branch-overlay-labels), or using the [SDK](/sdk-documentation/sdk-labels/sdk-label-versioning).

### View Label Branches

<div>
  <img />
</div>

<Note>
  This feature is only available to Workspace and Project Admins, and Team Managers in the REVIEW and COMPLETE Workflow stages.
</Note>

**To view labels from other branches:**

1. Click the **Branches** button in the Label Editor header.
   The branch overlay panel opens.

2. Select the checkboxes for the branches you want to overlay.
   Each branch displays with a unique color indicator.

3. Click outside the panel to close it.
   The selected branch labels now appear as read-only overlays in the 3D scene.

<Note>
  Branch label comparison is available in Review and Complete editor views — no feature flag or admin configuration required. Overlay labels are read-only. You cannot edit annotations from other branches directly in the overlay view.
</Note>

<Info>Audio and text-document modalities do not yet display branch names on overlay labels. The vertical fan-out uses fixed pixel offsets and is not collision-aware; in very dense scenes with many overlapping annotations, labels from multiple branches may still be difficult to read.</Info>

***

## Multi-Tile Label Operations

<Info>In Projects with multiple data tiles, label operations (tracking, interpolation, and deletion) now target the specific tile where the label is located, ensuring accurate operations across different data sources.</Info>

When working with Projects that contain multiple data tiles, the Label Editor automatically handles label operations based on the tile context. This means:

* **Tracking operations** apply to objects within their specific tile
* **Interpolation** works within the correct tile's frame range
* **Label deletion** removes labels from the appropriate tile
* **Navigation** automatically switches to the correct tile when needed

This tile-aware behavior ensures that your annotations remain accurate and operations are performed on the intended data, even when working with complex multi-tile projects.

***

## Download Bitmask Annotations as PNG

You can download bitmask annotations directly from the Label Editor as PNG image files without running a full project export. Each downloaded PNG renders the bitmask in its assigned annotation color.

**Download a single bitmask**

Right-click a bitmask annotation on the canvas and select **Download bitmask as image**. The editor downloads a PNG file for that bitmask.

**Download multiple selected bitmasks**

Select two or more bitmask annotations (hold <kbd>Shift</kbd> and click each one), then right-click any selected bitmask and choose **Download bitmasks as image**. The editor composites all selected bitmasks into a single PNG file.

**Download all bitmasks on the current frame**

Right-click anywhere on the canvas background (not on an annotation) and select **Download all bitmasks as image**. This option appears only when at least one bitmask annotation exists on the current frame. The editor composites all bitmasks on the frame into a single PNG file.

<Note>The **Download bitmask as image** and **Download bitmasks as image** options appear only for bitmask-type annotations. Non-bitmask shapes do not show these options in their context menus.</Note>

**Downloaded file naming**

Encord names downloaded PNG files using the following pattern:

`<data_title>_frame_<frame_index>_<label>.png`

* Special characters in the data title are replaced with underscores.
* For a single bitmask, `<label>` uses the annotation name and object ID.
* For multiple selected bitmasks, `<label>` is `bitmasks`.
* For the canvas-level download, `<label>` is `all_bitmasks`.

<Info>If a download fails, the editor displays an error notification.</Info>

***

## Controls Common To Both Modes

### Editor Timeline

The Editor timeline visualizes when objects and instances appear throughout videos, scenes, and audio files. The cursor tracks playback in real time, always reflecting the current frame. The timeline is shown by default and can be resized or hidden by dragging it up or down.

***

### Editor Header

<div>
  <img alt="Editor header menu" title="editor header" />
</div>

The Editor header at the top-right of the navigation bar contains buttons and menu items to perform labeling activities as well as manage general app settings and notifications.

| **Icon** | **Name**               | **Description**                                                                                                                                    |
| -------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img />  | Help                   | Links to the: quick start guide, documentation, learning hub, and Encord support team.                                                             |
| <img />  | Notifications          | Shows the current status and history of actions taken in the application. This includes uploading datasets, training models, and exporting labels. |
| <img />  | Share                  | Copies the URL of the asset currently being labeled or reviewed.                                                                                   |
| <img />  | Save labels            | Manually saves labels on the Encord server.                                                                                                        |
| <img />  | Label Editor settings  | Settings controlling your labeling and reviewing experience.                                                                                       |
| <img />  | Open metadata          | Display any metadata for the current asset.                                                                                                        |
| <img />  | Overlay label branches | Choose which label branches to display for the current asset.                                                                                      |

***

### Quick Toolbar

<div>
  <img alt="Quick toolbar" title="Quick toolbar" />
</div>

* Display settings: adjust brightness, contrast, and gamma, or select **Show grid** to overlay a grid on images, image groups, and videos. In **Grid settings**, set the grid size in pixels, color, and opacity. Your display settings persist across sessions.
* Rotate the asset
* Pin a new [Issue](/end-to-end/Features/issues-e2e)
* Center the asset
* Zoom in and out, view the rounded zoom percentage, and click the percentage to reset the zoom to 100% or the nearest permitted zoom limit

***

### Actions

The actions bar allows your to search for and access any actions and features within the Label Editor, for both the Annotate and Review modes.

***

### Issues and Comments

<Tip>
  * Add [Issue Tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags) to a Project to flexibly categorize and group your issues.

  * Use the [Issues tab of your Project Analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues) to learn about issues in your Project.

  A complete walkthrough of all things Issues and Comments related can be found [here](/end-to-end/Features/issues-e2e).
</Tip>

Issues can be added to annotation and review tasks to communicate with other users. All issues contain comment threads relating to the entire task or specific sections of the task. A small notification badge on the *Issues* icon displays the number of unresolved issues in a task.

<div>
  <iframe />
</div>

**Types of Issues**:

* **Label rejection**: Created when a reviewer rejects labels. The reviewer is prompted to provide a reason for the rejection in the form of a comment. If all instances in a frame or image are rejected, a separate rejection issue is created for each label. Labels with rejection issues display a red Issues icon next to the instance name, which turns green once the issue is resolved.

* **File**: Apply to the entire file and can be created at any stage within the Label Editor.

* **Pinned**: Apply to a specific part of the file or frame and can be created at any stage within the Label Editor. Red *Pin*  icons indicate unresolved issues and remain red until they are marked as resolved.

* **Frame**: Apply to a specific frame and can be created at any stage within the Label Editor. Frame issues can only be created when multiple frames are present; such as in a video, image sequence, or DICOM volume.

* **Frame range**: Apply to a range of frames and can be created at any stage within the Label Editor. Frame range issues can only be created when multiple frames are present; such as in a video, image sequence, or DICOM volume. Frame range issues can only be [created during label validation](/platform-documentation/Validation/active-basics/active-comments).

* **Task requirement**: Are created for each object or classification [marked *Required* in the Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#required-attributes). The issue is resolved when the required object or classification is applied. Task requirement issues are the only issues visible in a Consensus annotate stage.

<Tip>
  - Each issue card header shows its scope. For annotation issues, the scope displays the exact label name. Selecting the card highlights the associated label; clicking a frame chip navigates to that frame and selects the corresponding issue.
  - Issue threads can be filtered by *Resolved* and *Unresolved* issues.
</Tip>

**To Create a new Issue**:

<Note>
  Issues cannot be created in a Consensus annotate stage.
</Note>

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *New issue* icon (or keyboard shortcut <kbd>Ctrl</kbd>+<kbd>N</kbd>).
3. Click the *Apply to* dropdown to select the type of issue you want to create.
4. Select any [Issue Tags](/platform-documentation/General/general-workspace-settings#issue-tags) you want to apply to the issue.
5. Add a comment to the issue.
6. If you selected 'Pin on canvas' in Step 3, click the desired location on the canvas.
7. Click **Create issue**.

<div>
  <img />
</div>

**To Resolve an Issue:**

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *tick* to mark a thread as resolved.

Resolved issues remain visible but can be filtered out. All users can resolve issues.

<div>
  <img />
</div>

**To Delete an Issue Thread:**

<Warning>
  Deleted threads are NOT counted in the [Issues analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues).
</Warning>

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *Ellipsis* icon to show more options.
3. Click **Delete thread**.

<Note>
  Users can only delete issues that they created. **Label rejections cannot be deleted, only resolved**.
</Note>

**To Reopen an Issue Thread:**

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click *Reopen* on an issue that was previously resolved.

**Use Cases**:

* **Ask questions**: Annotators and reviewers can ask questions about the task. Admins can use this feedback to improve guidance.
* **Explain task rejection**: Reviewers can provide reasons for rejection, helping annotators avoid repeating mistakes.
* **Track unresolved issues**: Keep a record of open discussions that need follow-up before finalizing annotations.

***

### Editor Lock

The 'Editor lock' is a safety feature we implemented to prevent several people making changes to the same file - annotators labeling, or reviewers reviewing the same data unit.

A warning is triggered in two cases:

1. When you have the same task open in two different tabs or browser windows:

<div>
  <img />
</div>

2. When a different user is editing the same task:

<div>
  <img />
</div>

***

## WACOM Tablet Support

Our [Label Editor](/platform-documentation/Annotate/annotate-label-editor) fully supports Wacom tablets and pens. You get the best experience if you enable [freehand drawing mode](/platform-documentation/Annotate/annotate-label-editor#freehand-drawing--polygon-coarseness).


# Reviewer Label Editor Basics
Source: https://docs.encord.com/persona-taskers/tasker-label-editor-reviewer



<Info>To ensure seamless data loading in Encord, allowlist [https://app.encord.com/](https://app.encord.com/) or [https://app.us.encord.com/](https://app.us.encord.com/) in any 3rd party VPNs, firewalls, or URL isolators. This helps to prevent potential issues with opening your data in Encord.</Info>

This documentation provides a comprehensive guide to using the Label Editor for review, covering its components, features, and the display of various elements.

## Review Mode

### Introductory Video

The following video goes through the basics of reviewing visual data in the Label Editor.

<div>
  <iframe />
</div>

### Review Mode Components

As a reviewer, your Label Editor workspace contains the following components:

* **A**. Filter and search reviews
* **B**. [Labels to review](#single-label-review)
* **C**. [Quick toolbar](#quick-toolbar)
* **D**. [Single Label Review](#single-label-review)
* **E**. [Actions](#actions)
* **F**. [Reject and Approve buttons](#reject-and-approve-buttons)
* **G**. [Editor header](#editor-header)
* **H**. [Issues](/end-to-end/Features/issues-e2e)
* **I**. [Skip Task](#skip-a-review-task) and [Edit labels](#edit-labels-during-review) buttons
* **F**. [Reject and Approve buttons](#reject-and-approve-buttons)

<Note>
  Videos, Image Sequences, Scenes, and Audio display a [timeline](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#editor-timeline) in the Label Editor.
</Note>

<div>
  <img />
</div>

<Tip>
  Use the show-hide labels buttons, workspace settings, and the drag and select in the workspace to speed up your approved label selection and review process.

  ![Optimize Review](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/projects-review-labels.gif)
</Tip>

***

### Single Label Review

The normal review mode displays all labels simultaneously, allowing you to quickly approve or reject many labels in bulk actions. Alternately, enter the *Single label review* mode by toggling the switch at the top left. The single label review mode automatically highlights the selected instance, and hides all other objects. This allows you to carefully review one instance at a time including their attributes, and quickly iterate through the different instances using the *Up* and *Down* keys on your keyboard or by clicking the appropriate buttons in the UI.

<div>
  <img />
</div>

<Note>The *Single label review* feature can also be considered "turbo review mode," analogous to the "turbo attribute mode" in annotation mode, because it allows the reviewer to quickly step through and review instance attributes. "Turbo attribute mode" in the editor settings can be disabled while in review mode.</Note>

**Single Label Review Settings**

The default zoom level for single label review can be adjusted to suit your needs.

1. Open the [editor settings](#editor-settings-menu).

2. In the *General settings* section adjust the *Set the default zoom level for single label view* value highlighted in the screenshot below. The settings will be applied for the next selected label.

<div>
  <img />
</div>

<Note>
  * Initially, the default is set to 60%
  * 20% corresponds to no zoom. It's the magnification at which the image or frame is displayed in the Label Editor.
  * To zoom in, increase the percentage value.
  * To zoom out, decrease the percentage value. The minimum value is 1%.
</Note>

***

### Skip a Review Task

In the standard and configurable Label Editors, click **Skip** when you cannot complete a review task. You can enter an optional reason, then click **Skip task**. Skipping saves your label changes and unassigns you from the task. If another review task is available, it loads in the editor; otherwise, you return to the task queue. The skip and any reason you provide are added to the task as a comment.

***

### Edit Labels During Review

It is sometimes faster, more convenient, and less error-prone to have reviewers make edits to annotations, instead of outright rejecting them. Rejection requires the return of the entire set of labels to the annotator.

*Edit review* allows reviewers to make changes to labels, remove labels, and add new labels. Approved or rejected labels cannot be edited. Only *Pending* labels can be edited by reviewers. New labels made by editors are automatically approved, and cannot be changed once they have been saved. Once all labels have been approved the task moves to the *Complete* stage.

<Tip>We recommend enabling [*Strict review*](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#strict-review) on Review blocks when configuring Workflows. *Strict review* allows reviewers to revert approved labels back to *Pending*, giving reviewers the option to make changes to new labels drawn while editing labels. </Tip>

**To edit labels in review mode:**

1. Click the **Edit labels** button.

<div>
  <img />
</div>

2. Add or remove labels, or edit existing labels as necessary using the same interface annotators use to create labels.

3. Click the **Save and return to review** button to save your edits and return to review mode.

<Note>The **Save and return to review** button replaces the **Save** and **Cancel** buttons used in earlier versions of this feature.</Note>

<div>
  <img />
</div>

<Warning>
  * There is no way to edit Classifications.
  * Labels created during *Edit review* are not added to the Review stage and can not be seen in the Label Editor.
</Warning>

***

### Pending Reviews Pane

All labels for review for a particular data asset assigned to the reviewer are automatically loaded into then *Pending reviews* pane. The labels are grouped by Ontology class.

<Tip>
  You can search for specific classes and labels by clicking the **Search** button (magnifying glass icon) in the header within both the **Pending reviews** and **Completed reviews** panes to quickly locate the items you need to review.
</Tip>

***

### Completed Reviews Pane

Completed reviews are displayed in the *Completed reviews* pane. You can click on specific objects to highlight them. Labels can be selected and then approved or rejected for a given instance or in bulk using the **Reject** and **Approve** buttons or the matching hotkeys, <kbd>b</kbd> for reject and <kbd>n</kbd> for approve. Approved labels appear in a green background and rejected labels appear in red.

<Tip>
  You can search for specific classes and labels by clicking the **Search** button (magnifying glass icon) in the header within both the **Pending reviews** and **Completed reviews** panes to quickly locate the items you need to review.
</Tip>

***

### Approve and Reject All In Frame Buttons

The **Approve all in frame** and **Reject all in frame** buttons take the named action without having to select a particular instance or set of instances. This speeds up workflows, particularly in images, where you can judge whether all instances are correct or not by looking at an individual frame.

<Warning>The **Approve all in frame** and **Reject all in frame** buttons apply to all instances present in a frame, rather than labels. This means that all instances with labels in the current frame will have all of their labels approved or rejected.</Warning>

<Tip>The **Approve all in frame** and **Reject all in frame** buttons can be hidden in the [general settings](#general-settings).</Tip>

***

### Reject and Approve Buttons

To reject/approve multiple object instances across frames, select the instances, and then click the **Reject** or **Approve** button, as appropriate. Alternately, you may press <kbd>b</kbd> for reject and <kbd>n</kbd> for approve.

***

### Review Status Color Mode

When **Label color mode (review)** is set to **By review status** in the editor settings, labels are recolored to reflect their current review state:

* **Pending** — orange
* **Approved** — green
* **Rejected** — red

Labels that you approve or reject during the current session fade to the opacity level configured by the **Reviewed label opacity** setting, making it easier to track your progress through a dense set of labels.

<Note>
  **By review status** color mode and **Reviewed label opacity** now apply to all 3D label types in point-cloud review tasks, including cuboids, spheres, polylines, and keypoints/points. This brings 3D review workflows to visual parity with 2D review.

  The opacity fade applies only to filled shapes (cuboids and spheres). Polylines and keypoints/points are recolored by review status but do not fade. For full details on 3D-specific behavior, see the [point cloud editor documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-pcd).

  This color mode is active in both standard workflow review mode and consensus review mode. It has no effect outside a review stage.
</Note>

***

### Change Review Judgement

<AccordionGroup>
  <Accordion title=" Video Tutorial - Strict review & change review judgment ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

Reviewed instances can be reverted to [*pending*](/platform-documentation/Annotate/annotate-label-editor#pending-reviews-pane). Reverting a review allows reviewers to make adjustments to one or more instances after making their initial review.

<div>
  <img />
</div>

1. Revert labels to *pending* :

* Revert an approved task to *pending* by clicking the green tick icon next to the instance.
* Revert a rejected task to *pending* by clicking the red cross icon next to the instance.

2. Once the reviewer completes their review, they need to click the **Approve task** or **Reject task** to finalize the review.

***

## Controls Common To Both Modes

### Editor Timeline

The Editor timeline visualizes when objects and instances appear throughout videos, scenes, and audio files. The cursor tracks playback in real time, always reflecting the current frame. The timeline is shown by default and can be resized or hidden by dragging it up or down.

***

### Editor Header

<div>
  <img alt="Editor header menu" title="editor header" />
</div>

The Editor header at the top-right of the navigation bar contains buttons and menu items to perform labeling activities as well as manage general app settings and notifications.

| **Icon** | **Name**               | **Description**                                                                                                                                    |
| -------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img />  | Help                   | Links to the: quick start guide, documentation, learning hub, and Encord support team.                                                             |
| <img />  | Notifications          | Shows the current status and history of actions taken in the application. This includes uploading datasets, training models, and exporting labels. |
| <img />  | Share                  | Copies the URL of the asset currently being labeled or reviewed.                                                                                   |
| <img />  | Save labels            | Manually saves labels on the Encord server.                                                                                                        |
| <img />  | Label Editor settings  | Settings controlling your labeling and reviewing experience.                                                                                       |
| <img />  | Open metadata          | Display any metadata for the current asset.                                                                                                        |
| <img />  | Overlay label branches | Choose which label branches to display for the current asset.                                                                                      |

***

### Quick Toolbar

<div>
  <img alt="Quick toolbar" title="Quick toolbar" />
</div>

* Display settings: adjust brightness, contrast, and gamma, or select **Show grid** to overlay a grid on images, image groups, and videos. In **Grid settings**, set the grid size in pixels, color, and opacity. Your display settings persist across sessions.
* Rotate the asset
* Pin a new [Issue](/end-to-end/Features/issues-e2e)
* Center the asset
* Zoom in and out, view the rounded zoom percentage, and click the percentage to reset the zoom to 100% or the nearest permitted zoom limit

***

### Actions

The actions bar allows your to search for and access any actions and features within the Label Editor, for both the Annotate and Review modes.

***

### Issues and Comments

<Tip>
  * Add [Issue Tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags) to a Project to flexibly categorize and group your issues.

  * Use the [Issues tab of your Project Analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues) to learn about issues in your Project.

  A complete walkthrough of all things Issues and Comments related can be found [here](/end-to-end/Features/issues-e2e).
</Tip>

Issues can be added to annotation and review tasks to communicate with other users. All issues contain comment threads relating to the entire task or specific sections of the task. A small notification badge on the *Issues* icon displays the number of unresolved issues in a task.

<div>
  <iframe />
</div>

**Types of Issues**:

* **Label rejection**: Created when a reviewer rejects labels. The reviewer is prompted to provide a reason for the rejection in the form of a comment. If all instances in a frame or image are rejected, a separate rejection issue is created for each label. Labels with rejection issues display a red Issues icon next to the instance name, which turns green once the issue is resolved.

* **File**: Apply to the entire file and can be created at any stage within the Label Editor.

* **Pinned**: Apply to a specific part of the file or frame and can be created at any stage within the Label Editor. Red *Pin*  icons indicate unresolved issues and remain red until they are marked as resolved.

* **Frame**: Apply to a specific frame and can be created at any stage within the Label Editor. Frame issues can only be created when multiple frames are present; such as in a video, image sequence, or DICOM volume.

* **Frame range**: Apply to a range of frames and can be created at any stage within the Label Editor. Frame range issues can only be created when multiple frames are present; such as in a video, image sequence, or DICOM volume. Frame range issues can only be [created during label validation](/platform-documentation/Validation/active-basics/active-comments).

* **Task requirement**: Are created for each object or classification [marked *Required* in the Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#required-attributes). The issue is resolved when the required object or classification is applied. Task requirement issues are the only issues visible in a Consensus annotate stage.

<Tip>
  - Each issue card header shows its scope. For annotation issues, the scope displays the exact label name. Selecting the card highlights the associated label; clicking a frame chip navigates to that frame and selects the corresponding issue.
  - Issue threads can be filtered by *Resolved* and *Unresolved* issues.
</Tip>

**To Create a new Issue**:

<Note>
  Issues cannot be created in a Consensus annotate stage.
</Note>

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *New issue* icon (or keyboard shortcut <kbd>Ctrl</kbd>+<kbd>N</kbd>).
3. Click the *Apply to* dropdown to select the type of issue you want to create.
4. Select any [Issue Tags](/platform-documentation/General/general-workspace-settings#issue-tags) you want to apply to the issue.
5. Add a comment to the issue.
6. If you selected 'Pin on canvas' in Step 3, click the desired location on the canvas.
7. Click **Create issue**.

<div>
  <img />
</div>

**To Resolve an Issue:**

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *tick* to mark a thread as resolved.

Resolved issues remain visible but can be filtered out. All users can resolve issues.

<div>
  <img />
</div>

**To Delete an Issue Thread:**

<Warning>
  Deleted threads are NOT counted in the [Issues analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues).
</Warning>

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *Ellipsis* icon to show more options.
3. Click **Delete thread**.

<Note>
  Users can only delete issues that they created. **Label rejections cannot be deleted, only resolved**.
</Note>

**To Reopen an Issue Thread:**

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click *Reopen* on an issue that was previously resolved.

**Use Cases**:

* **Ask questions**: Annotators and reviewers can ask questions about the task. Admins can use this feedback to improve guidance.
* **Explain task rejection**: Reviewers can provide reasons for rejection, helping annotators avoid repeating mistakes.
* **Track unresolved issues**: Keep a record of open discussions that need follow-up before finalizing annotations.

***

### Editor Lock

The 'Editor lock' is a safety feature we implemented to prevent several people making changes to the same file - annotators labeling, or reviewers reviewing the same data unit.

A warning is triggered in two cases:

1. When you have the same task open in two different tabs or browser windows:

<div>
  <img />
</div>

2. When a different user is editing the same task:

<div>
  <img />
</div>


# Tasker (Annotator/Reviewer) Quickstart
Source: https://docs.encord.com/persona-taskers/tasker-quick-start



As an Annotator or a Reviewer, you spend most of your time in the Label Editor and the Project Queue.

## Task Queue

The Project Task Queue provides a list of tasks for you to annotate, review, or annotate and review.

You can search, sort, and filter the contents of the Queue. Tasks with the highest priority and tasks that are reopened appear at the top of the Queue.

<iframe title="YouTube video player" />

## Label Editor

The Label Editor provides the space where you annotate or review tasks.

<Tip>
  Configure Label Editor settings before you start annotating or reviewing. Optimized settings can streamline your annotation and reviewing process.
</Tip>

**Annotator**

<iframe title="YouTube video player" />

**Reviewer**

<iframe title="YouTube video player" />

## Quick Start Template Projects

When you create a new Project using a Quick Start template, Encord automatically opens the Project on the **Summary** page with the **Preview** tab active. This gives you an immediate visual preview of your new Project without any extra navigation.

## Analytics

As an Annotator, Reviewer, or Annotator-Reviewer, you can monitor your performance using the Analytics page.

**Annotator**

<iframe title="YouTube video player" />

**Reviewer**

<iframe title="YouTube video player" />


# Review Tasks
Source: https://docs.encord.com/persona-taskers/tasker-review



Reviewing tasks involves the following:

* Approving or rejecting labels
* Adding and editing labels
* Adding **Issues** for Annotators to address
* Approving or rejecting Tasks

<Note>
  - Depending on your company's process to create and validate labels, your role as a Reviewer might not include adding or editing labels or creating Issues for Annotators.

  - Reviewers have the ability to reject or approve tasks even if all a task has Issues or rejected labels.

  - Reviewers cannot skip tasks. Tasks in a REVIEW block can only be approved or rejected.
</Note>

## Review Standard Projects

Standard Projects can have multiple Annotators. Each Task is labeled by a single Annotator or Agent. Reviewers perform reviews on the Tasks and Approve or Reject according to their company's standards and processes.

### Review Images and Videos

Use the timeline to help when reviewing videos.

<iframe title="YouTube video player" />

### Review Audio Files

Use the timeline to help when reviewing videos.

Show and hide audio regions while reviewing.

<iframe title="YouTube video player" />

### Review Point Cloud Data

<video />

### Review Text and HTML

<video />

### Review PDFs

<iframe title="YouTube video player" />

### Review Multi-modal Tasks

Multi-modal tasks can include any type of data unit type. We recommend referring to the other data unit types to understand how to review multi-modal data units.

## Review Consensus Projects

Consensus Projects have multiple Annotators. Each Task is labeled by 2 or more Annotators or Agents. Reviewers review and select all labels on the Tasks from all Annotators. Reviewers then Approve or Reject Tasks according to their company's standards and processes.

Consensus Projects belong to the following categories:

* Review and Refine: In Review and Refine Projects, you can select the best labels from any annotator. You can also edit or create new labels on the data unit.
* Determine Consensus: In Determine Consensus Projects, you specify the annotators that are in consensus for all labels on the data unit, and then you select the annotator with the best labels to apply to the data unit. You cannot add or edit any labels on the data unit.


# Taskers - Annotators and Reviewers
Source: https://docs.encord.com/persona-taskers/taskers-index



<span>
  Workspace Role
</span>

The workspace role "Taskers" is purpose built for Annotators, Reviewers, and Annotator-Reviewers on Projects.

* Annotators, Reviewers and Annotator-Reviewers all work on Tasks.
* Annotators label tasks using object labels or classifications.
* Reviewers review object labels or classifications.
* Annotator-Reviewers can both label Tasks and review Tasks.


# Video Label Validation
Source: https://docs.encord.com/platform-documentation/Annotate/active-annotate/basics/annotate-video-metrics-label-validation



Use the *Video* tab to natively view all the videos available in your Project. Videos appear as a grid of compact cards. Hover over a card to preview it, or click **+ N frames** to expand a video in place and inspect its frames. From the *Video* tab you can sort and filter all of your videos based on [Video Quality Metrics](/platform-documentation/Validation/label-validation-basics#quality-metrics) and several Annotation Quality Metrics made exclusively for video (Broken Track, Inconsistent Class, and Inconsistent Track). You can also apply video frame-level metrics while in the *Video* tab.

<iframe title="YouTube video player" />

1. Video Quality Metrics for sorting and filtering your videos.

2. A compact card grid of all videos in the Project. Click **+ N frames** on a card to expand it into a full-width frame strip with a slider to move through its frames in sequence.

3. Video frame-level metrics, shown once a video is expanded.

4. Label level quality metrics, for example Broken Track, Inconsistent Class, and Inconsistent Track.

## Use Video Quality Metrics

Use Video Quality Metrics to sort and filter your videos. For a full list refer to [Video Quality Metrics](/platform-documentation/Validation/label-validation-basics#quality-metrics).

<iframe title="YouTube video player" />

## Use video specific Annotation Metrics

When using Annotation Metrics, you need to switch to the *Labels* tab after selecting your video.

Remember your videos must have labels on some frames for the Annotation Quality Metrics to be useful.

<iframe title="YouTube video player" />

1. Log into Encord.\
   The Encord home page appears.

2. Click **Projects**.\
   The Project list page appears.

3. Click a Project that contains videos.

4. Click **Explore** > **Video**.

5. Sort and filter the videos using the Label Quality Metrics to find the video you want.

6. Apply one of following Annotation Quality Metric filters to your video:

   * Broken track
   * Inconsistent track
   * Inconsistent class

7. Click the **Expand image** button.\
   A larger version of the image appears.

8. Click **Edit in Annotate**.\
   The frame opens in the Label Editor in Annotate.

9. Move forward and backward a few frames in the video to see the labeling error.

### Find Broken Tracks

"Broken tracks" are cases where an object is being tracked (labeled) across a range of frames, but one or more frames in the range are missing labels. Hence, the tracking of the object across the video is broken.

Apply the Annotation Label Quality metric **Broken Track** to filter the video for broken tracking of an object.

<div>
  <img alt="Broken Tracks Sequence" />
</div>

<div>
  <img alt="Broken Tracks Sequence" />
</div>

<div>
  <img alt="Broken Tracks Sequence" />
</div>

**Caveat**

This metric naturally flags samples that might not be relevant. For example, where an object (the green one) is occluded and reappears.

<div>
  <img alt="Broken Tracks Sequence - Caveat" />
</div>

<div>
  <img alt="Broken Tracks Sequence - Caveat" />
</div>

<div>
  <img alt="Broken Tracks Sequence - Caveat" />
</div>

### Find Inconsistent Tracks

"Inconsistent tracks" are cases an object is being tracked (labeled) across a range of frames, but the occurrence of the label changes part way through tracking the object. For example, you want to track two cars across an entire video. At some point in the video, the labels on the cars are swapped OR a new label gets applied to one or both of the cars.

For example, for two neighboring frames, say `t`\$ and `t+1`, we assume that for every object `o* i,t` in frame `t`, the object `o* i, t+1` in frame `t+1` with the highest IOU to `o* i, t` should have the same `objectHash.`

For every object in frame `t`, the algorithm works by computing the IOU between that object and every object in frame `t+1` to select the one with the highest IOU. If those two objects have the same objectHash, all good, score will be zero. There’s nothing to flag. If, on the other hand, the two objects do not share the same objectHash, it’s flagged by setting the score to the IOU between the two.

Think of `o* i, t` as the best match (highest IOU) in the following frame.

![](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/formula-01.png)

In the above, we use `o i,t. ID` as a shorthand for objectHash.

In turn,

* A score equal to 0 means that no issues were found.
* A score close to zero (but not zero) means that there is inconsistency in the object hashes but the objects do not overlap much, so it is less likely to be an actual label error.
* A score closer to one means that the two objects have a high overlap and inconsistency in object hash.

**Example**

In this example, one track is inconsistent. The green guy has had objectHash `hYK5AFR6` for a while, and suddenly it changes to `H1ca7QwH`. Also indicated here by color (which would not actually be the case in the editor).

<div>
  <img alt="Inconsistent Tracks Sequence" />
</div>

<div>
  <img alt="Inconsistent Tracks Sequence" />
</div>

<div>
  <img alt="Inconsistent Tracks Sequence" />
</div>

**Special case**

This algorithm also works for classifications. However, in that situation, the IOU falls back to the identity function

![](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/formula-02.png)

### Find Inconsistent Classes

"Inconsistent classes" are similar to Inconsistent Tracking, but the scoring function cares about classification rather than objectHash:

![](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/formula-03.png)

Why is this useful? In some situations, track ids are not relevant but the classification is. For example, if you know there is only ever one instance of an object per frame, then id is implicitly defined. Such situations do not necessarily work with the “Inconsistent Tracks” metric but should with the classification metric.

An example of the is panoptic segmentation where some classes are “stuff classes” (like the dirt class). Stuff classes would usually only have one instance per frame.

### Use Video-Specific Metrics

Remember your videos must have labels on some frames for the Annotation Quality Metrics to be useful.

1. Navigate **Projects** and select a Project.

2. Open a Project that contains videos.

3. Click **Explore**

4. Click **Video**.

![Video Label Quality Metrics](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-video-label-metrics.gif)

5. Sort and filter the videos using the Label Quality Metrics to find the video you want.

6. Apply one of following Annotation Quality Metric filters to your video:

   * Broken track
   * Inconsistent track
   * Inconsistent class

7. Click the **Expand image** button.\
   A larger version of the image appears.

8. Click **Edit in Annotate**.\
   The frame opens in the Label Editor in Annotate.

9. Move forward and backward a few frames in the video to see the labeling error.


# Datasets
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-datasets/annotate-datasets



Datasets are subsets of your files that can be attached to one or more Projects for annotation. Datasets are created from files you upload to Encord.

## Creating Datasets

1. Click the **New dataset** button in **Data** > **Datasets**.

<div>
  <img />
</div>

2. Give your Dataset a meaningful title and description. A clear title and description keeps your data organized.

<Tip>Toggle **Looking to create a mirrored dataset?** to create a [Mirrored Dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets#mirrored-datasets). </Tip>

<div>
  <img />
</div>

3. Click **Create dataset** to create the Dataset.

## Attach Data

After a Dataset has been created, you can attach data.

<Tip>
  To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import and registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord.
</Tip>

1. Navigate to **Data** > **Datasets**
2. Click the Dataset you want to add data to.
3. Click **+Attach existing files**.

<div>
  <img />
</div>

4. Select the folders containing the files you want to attach to the Dataset. To select individual files, double-click a folder to see its contents, and select the files you want to add to the Dataset.

5. Click **Attach data** to attach the selected files to the Dataset.

***

## Attach Dataset to Project

You can attach Datasets (mirrored and static) to Projects, you own, directly from the summary page for the Dataset.

<Note>
  Empty Datasets can be added to Projects you own.
</Note>

<iframe title="YouTube video player" />

1. Navigate to **Annotate** > **Datasets**.

2. Click the Dataset you want to attach to a Project you own.

3. Click the **Attach to project** button.

   A list of the Projects you own appears.

4. Search for a Project from the Project list.

5. Click the Project you want to attach the Dataset to.

   A popup appears confirming the Dataset attached to the Project.

***

## Register Cloud Data to Datasets

<Tip>We recommend registering files in batches not exceeding 2GB, to ensure upload does not exceed 3 hours.</Tip>

1. [Create a Dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets#creating-datasets).

2. Select the Dataset you want to add data to.

3. Click **+ Add data**.

<div>
  <img />
</div>

4. Select a folder to store the files in, or create a new folder.

5. Select the *Import from private cloud* tab and select the integration you want to use.

<div>
  <img />
</div>

6. Click **Add JSON or CSV files** to upload a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying the cloud data that is to be added to the Dataset. Turn on the **Ignore individual file errors** toggle to ignore errors caused by files not supported by Encord.

<div>
  <img />
</div>

<Tip>We recommend enabling the **Ignore individual file errors** toggle. This ensures that the entire upload does not fail if only one file cannot be added.</Tip>

7. Click **Import** to add your cloud data to the Dataset.

<Note>The data is fetched from your cloud storage and processed asynchronously. This involves fetching appropriate metadata and other file information to help us render the files appropriately and to check for any framerate inconsistencies. We do not store your files in any way.</Note>

***

## Mirrored Datasets

<Info>
  Mirrored datasets simplify setup at the cost of flexibility. If you need more control over your data, use a standard folder and Dataset instead.
</Info>

A mirrored Dataset is a dataset backed by a folder. The Dataset and its backing folder are kept in sync automatically and changes made to either are reflected in the other. The mirroring is continuous and automatic.

* Files cannot be added to multiple Datasets.
* Every file added to the dataset appears in the backing folder.
* Every file added to the backing folder appears in the Dataset.
* Deletions are mirrored in both directions.

***

## Entity Relationships

The following diagram illustrates how Datasets relate to other entities in Encord.

The following diagram shows how entities in Encord are organized.

```mermaid theme={"dark"}
erDiagram
    Project {
        string project_hash
    }
    DataUnit {
        string data_hash
        string data_title
        string client_metadata
    }
    Dataset {
        string dataset_hash
        string dataset_title
    }
    Ontology {
        string ontology_hash
        string ontology_name
        string ontology_description
    }
    Workflow {
        string workflow_hash
    }
    Collaborator {
        string user
    }

    Project ||--o| Dataset : "attaches"
    Project ||--o| Ontology : "attaches"
    Project ||--o| Workflow : "follows"
    Project ||--o{ Collaborator : "includes"
    Dataset ||--o{ DataUnit : "composed of"
```

* Projects bring together Ontologies, Datasets, Workflows, and collaborators.
* A Project can have multiple Datasets attached to it, but only one Ontology.
* One Ontology can be attached to multiple Projects.

***

## Roles and Permissions

Collaborator permissions can be set in the *Team* section of the Dataset *Settings*.

<div>
  | Permission      | Admin | Viewer |
  | --------------- | ----- | ------ |
  | View dataset    | ✅     | ✅      |
  | Add data        | ✅     | ❌      |
  | Adjust settings | ✅     | ❌      |
</div>

***

## Manage Files and Users

To manage a Dataset's files and users, select it from the list.

<div>
  <img />
</div>

* The **Data tab** handles file management and displays the exact count of items in your Dataset
* The **Settings tab** is for user management, viewing linked Projects, and deleting the Dataset.

<AccordionGroup>
  <Accordion title="Data tab">
    <div>
      <img />
    </div>

    The **Data tab** shows the precise number of items in your Dataset. For example, displaying `1,234 items` instead of `1.2k items`.
  </Accordion>

  <Accordion title="Settings tab">
    <div>
      <img />
    </div>

    **To add collaborators to the Dataset**:

    1. Search for the collaborator or the [group](/platform-documentation/General/general-workspace-settings#user-groups) you want to add. Multiple collaborators and groups can be added at once.

    <Note>
      Only group members are added when a group is assigned to a Project. Group managers are not included.
    </Note>

    2. Select a user role.

    * **User**: Can view the Dataset and attach it to Projects.
    * **Admin**: Grants full administrative control over the Dataset.

    3. Click **Add to dataset**.

    <Info>
      * Change a user's role by clicking their role in the *Role* column and selecting a new one.
      * Remove users by clicking the *Delete* icon in the *Unassign* column.
    </Info>
  </Accordion>
</AccordionGroup>

***

## Automated Data Flows

Datasets linked to auto sync folders with continuous data flows enabled display a section called "Automated data flow enabled" that show a green "Live" indicator. This helps you quickly identify that the Dataset is receiving automated data processing.

***

## Delete Dataset

Use the *Danger zone* pane in **Settings** to delete Datasets.

<img />

Click the **Delete dataset** button to delete the entire Dataset. You are prompted to type the word 'delete' into the resulting pop-up to delete the Dataset.

<Warning>Deleting a Dataset cannot be undone. Make sure you want to perform this action before continuing.</Warning>

***

## Joining Datasets in your Workspace

Workspace Admins can search for and join any Datasets that exist within the Workspace.

1. Navigate to **Data** > **Datasets** in the Encord platform.
2. Select the **All Encord datasets** tab.
3. Find the Dataset you want to join.
4. Click **Join dataset** to join the Dataset.

<div>
  <img />
</div>

When a Workspace Admin joins a Dataset, they are automatically assigned the *Admin* [user role for that Dataset](/platform-documentation/Annotate/roles-and-permissions#datasets).

<Tip>Datasets can be filtered by Dataset owner.</Tip>

<Tip>See all Datasets you belong to by clicking the *Filter by* search bar, and selecting  *My datasets only*. </Tip>


# COCO Format Export
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-export-coco



<Warning>
  If using Windows, we recommend using [7-Zip](https://www.7-zip.org/) to unzip the exported labels.
</Warning>

<Warning>
  COCO export is not available for PCD scenes.
</Warning>

<Info>
  All coordinates in the COCO format correspond directly to pixel values. Refer to the [COCO documentation](https://cocodataset.org/#home) for details on the COCO format.
</Info>

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.

| **Key**             | **Description**                                                                                                                                                                                                                                                                                                     | **Notes**                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `annotations`       | Contains all label information                                                                                                                                                                                                                                                                                      |                                                                                                                                                                 |
| `area`              | The area contained by the label                                                                                                                                                                                                                                                                                     | in units of square pixels                                                                                                                                       |
| `attributes`        | A list of attributes belonging to a label                                                                                                                                                                                                                                                                           |                                                                                                                                                                 |
| `classifications`   | All radio and checklist attributes and their answers                                                                                                                                                                                                                                                                |                                                                                                                                                                 |
| `#relation`         | The hash of the ontology object the label is related to                                                                                                                                                                                                                                                             | The hash is the object's unique identifier                                                                                                                      |
| `encord_track_uuid` | A unique identifier for the object instance                                                                                                                                                                                                                                                                         | The same as the `objectHash` in a JSON export.                                                                                                                  |
| `manual_annotation` | Indicates whether the annotation was created manually.                                                                                                                                                                                                                                                              | `True` is the annotation is manual, `False` if created using automated labeling techniques                                                                      |
| `track_id`          | The unique identifier for the instance the label is associated with                                                                                                                                                                                                                                                 | The value is the same for all annotations belonging to the same instance                                                                                        |
| `bbox`              | Pixel coordinates for the top-left corner of a bounding box that encloses the label. This is provided for all shape types.                                                                                                                                                                                          |                                                                                                                                                                 |
| `category_id`       | A numerical ID linking this annotation to a field in the `categories` list containing Ontology information.                                                                                                                                                                                                         | For example, the `category_id` value `1` in an annotation links it to the corresponding Ontology shape with the ID `1` in the `categories` field of the export. |
| `id`                | The unique identifier for the label                                                                                                                                                                                                                                                                                 | Each label has a unique identifier, irrespective of which instance it is associated with                                                                        |
| `image_id`          | The ID of the image or frame the label is on                                                                                                                                                                                                                                                                        | For example, ID `0`  indicates that the label is on the first image in the `images` list of the export                                                          |
| `iscrowd`           | The `iscrowd` field specifies whether the annotation represents a single object (`iscrowd=0`, using polygons) or a collection of objects (`iscrowd=1`, using RLE). Single objects may require multiple polygons if occluded, while crowd annotations are used for large groups of objects (e.g., a crowd of people) |                                                                                                                                                                 |
| `keypoints`         | The keypoints field is a list of coordinates and visibility flags for specific points on an object                                                                                                                                                                                                                  |                                                                                                                                                                 |
| `num_keypoints`     | The num\_keypoints field indicates the number of labeled keypoints (v > 0) for an object. Objects without labeled keypoints (e.g., small or crowd objects) have num\_keypoints=0                                                                                                                                    | Keypoints and their connections (skeletons) are defined in the categories section, which includes the names and connectivity of the keypoints for visualization |
| `segmentation`      | Contains the (x,y)  pixel coordinates for all label vertices                                                                                                                                                                                                                                                        |                                                                                                                                                                 |
| `categories`        | Contains Ontology information                                                                                                                                                                                                                                                                                       |                                                                                                                                                                 |
| `name`              | The object's name in the Ontology                                                                                                                                                                                                                                                                                   |                                                                                                                                                                 |
| `supercategory`     | The name of the object's class                                                                                                                                                                                                                                                                                      |                                                                                                                                                                 |
| `keypoints`         | `keypoint` for keypoint labels. Omitted for all other labels                                                                                                                                                                                                                                                        |                                                                                                                                                                 |
| `skeleton`          | Defines connectivity via a list of keypoint edge pairs and is used for visualization                                                                                                                                                                                                                                |                                                                                                                                                                 |
| `images`            | Contains file information for all modalities                                                                                                                                                                                                                                                                        |                                                                                                                                                                 |
| `coco_url`          | URL to the file if it is hosted on the COCO dataset’s official servers                                                                                                                                                                                                                                              | Only meaningful when working with the official COCO tasks. In all other cases the `coco_url` field is empty.                                                    |
| `file_name`         | The name of the file                                                                                                                                                                                                                                                                                                |                                                                                                                                                                 |
| `height`            | The height of the image or frame                                                                                                                                                                                                                                                                                    | Measured in pixels                                                                                                                                              |
| `image_title`       | The title of the file                                                                                                                                                                                                                                                                                               |                                                                                                                                                                 |
| `width`             | The width of the image or frame                                                                                                                                                                                                                                                                                     | Measured in pixels                                                                                                                                              |
| `info`              | Contains additional information                                                                                                                                                                                                                                                                                     |                                                                                                                                                                 |


# JSON Format Export
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-export-json



<Warning>
  If using Windows, we recommend using [7-Zip](https://www.7-zip.org/) to unzip the exported labels.
</Warning>

## Label Coordinates

In the JSON format, label coordinates are normalized to be between 0 and 1. This means that the corners of the frame or image correspond to the coordinates (1,1), (1,0), (0,0), (0,1) regardless of frame dimensions.

To get the pixel values of normalized coordinates:

* The `x` and `h` coordinates of a label should be multiplied by the pixel width of the frame or image.
* The `y` and `w` coordinates of a label should be multiplied by the pixel height of the frame or image.

<div>
  <img />
</div>

***

## Format of Exported Labels

<Warning>
  The `last_edited_by` and `last_edited_at` fields are updated only when the label or its nested attributes are modified in the Label Editor. If the SDK is used to update the label, these fields must be updated manually.
</Warning>

The tables below provide descriptions of all values contained JSON format exports.

<Note>Exports of label versions for which the data unit was deleted vary from the examples shown below - the `data_type` is `deleted`, while image groups and image sequences only contain a single `data_unit`.</Note>

Exported labels include several unique identifiers that nest. The root of each label starts with the `object_hash` for the Ontology object or classification.

![Exported Label Structure](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/labels-export-structure.jpg)

### Single Images

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.

```json theme={"dark"}
[
    {
        "classification_answers": {},
        "created_at": "2025-01-07 16:12:23",
        "data_hash": "f3132c00-069f-4a95-8e21-30c13078d84d",
        "data_title": "Image3.jpg",
        "data_type": "image",
        "data_units": {
        },
        "dataset_hash": "3c35b0f2-64fc-4a58-9b9d-f7181d73f1e5",
        "dataset_title": "New Welsh Whales",
        "is_image_sequence": null,
        "is_valid": true,
        "label_hash": "0f5a5e62-a3e0-4481-932f-1093f7c1d170",
        "label_status": "LABEL_IN_PROGRESS",
        "last_edited_at": "2025-01-07 16:12:23",
        "object_actions": {},
        "object_answers": {},
        "video_link": null
    }
]
```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The Dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| data\_type              | The data unit's file format                                                                                                                        | Always "video" for videos                                                                                                                |
| is\_image\_sequence     | "true" when the data unit is an image sequence                                                                                                     | Always "null" for images                                                                                                                 |
| video\_link             | Contains a private cloud URL for videos                                                                                                            | Always "null" for images                                                                                                                 |
| data\_units             | List of all files the data unit is composed of                                                                                                     | Details of the export information for \`data\_units\`\` can be found below.                                                              |
| object\_answers         | All the attributes in this data unit                                                                                                               | The object attributes are identified using their hash                                                                                    |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled.                                                                                                  |                                                                                                                                          |
| export\_history         | Contains a record of the export history for this data unit                                                                                         | Exporting labels to confirm export history generates an export history entry.                                                            |
| export\_hash            | The hash for this particular export instance                                                                                                       | The 'hash' represents a unique identifier                                                                                                |
| exported\_at            | The date and time when a particular export instance took place.                                                                                    |                                                                                                                                          |

<AccordionGroup>
  <Accordion title="data_units">
    The `data_units` key contains all files that compose the data unit. For a given image there is only ever a single element in this list. This element contains the following information.

    <Warning>`data_units` here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.</Warning>

    ```json theme={"dark"}

    "data_units": {
          "9c588f63-ad87-4987-a074-06ba0d6980cd": {
            "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
            "data_title": "dom-hbf.jpg",
            "data_type": "image",
            "data_sequence": 0,
            "labels": { },
            "data_fps": "23.976023976023978" ,
            "data_duration": "29.0786",
            "data_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
            "width": 512,
            "height": 512
          }
    }  
    ```

    | **Key**        | **Description**                                       | **Notes**                                                                           |
    | -------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
    | data\_hash     | The file's hash                                       | The 'hash' represents a unique identifier                                           |
    | data\_title    | The file's title                                      |                                                                                     |
    | data\_type     | The file type                                         |                                                                                     |
    | data\_sequence | The sequence number of this file within the data unit | Always `0` for images, as single images are composed of a single file by definition |
    | labels         | A container for the image's label information         | This contains the label information for the image.                                  |
    | data\_link     | A link to the file stored in your private cloud       |                                                                                     |
    | width          | The width of the image in pixel (px)                  |                                                                                     |
    | height         | The height of the image in pixel (px)                 |                                                                                     |

    <AccordionGroup>
      <Accordion title="labels">
        `labels` contains all object labels, classification labels, and attributes present in the image.

        ```json theme={"dark"}

        "labels": {
              "0": {
                "objects": { },
                "classifications": [ ]
              }
        }  
        ```

        | **Key**         | **Description**                                        | **Notes**                                        |
        | --------------- | ------------------------------------------------------ | ------------------------------------------------ |
        | objects         | A list of label objects in this frame                  | Contains geometric information for object labels |
        | classifications | A list of classifications applying to image as a whole |                                                  |

        <AccordionGroup>
          <Accordion title="objects">
            `objects` contains all object label information for the image. A key with the name of the object shape is always present - `bounding_box` in the example below. All shapes contain coordinates for each vertex.

            <Tip>Navigate to the [ontology shapes section](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) to see how all ontology classes are represented in the exported file.</Tip>

            The example below shows a single object instance.

            ```json theme={"dark"}
            {
            "objects": [
            {
            "featureHash": "Aav9W+cC",
            "objectHash": "cTkqn7d7",
            "name": "Cherries",
            "value": "cherries",
            "color": "#595feb",
            "shape": "bounding_box",
            "confidence": 1,
            "frame": 0,
            "createdBy": "chris-encord@acme.com",
            "createdAt": "Wed, 28 May 2025 08:51:53 GMT",
            "lastEditedBy": "chris-encord@acme.com",
            "lastEditedAt": "Wed, 28 May 2025 08:51:53 GMT",
            "manualAnnotation": true,
            "boundingBox": {
              "x": 0.34688227662041876,
              "y": 0.4167629800853485,
              "w": 0.29148041861853874,
              "h": 0.41461619320558957
            }
            }
            ]
            }

            ```

            <table>
              <thead>
                <tr>
                  <th>**Key**</th>
                  <th>**Description**</th>
                  <th>**Notes**</th>
                </tr>
              </thead>

              <tbody>
                <tr>
                  <td>objectHash</td>
                  <td>The specific label's hash</td>
                  <td>The 'hash' represents a unique identifier</td>
                </tr>

                <tr>
                  <td>featureHash</td>
                  <td>The Ontology object's hash</td>
                  <td>Corresponds to the FeatureNodeHash in the ontology </td>
                </tr>

                <tr>
                  <td>name</td>
                  <td>The object's name</td>
                  <td>As specified in the ontology</td>
                </tr>

                <tr>
                  <td>value</td>
                  <td>The name given to the object</td>

                  <td />
                </tr>

                <tr>
                  <td>color</td>
                  <td>The color used to draw the object</td>
                  <td>As specified in the ontology</td>
                </tr>

                <tr>
                  <td>shape</td>
                  <td>The Ontology class used to create the object</td>
                  <td>As specified in the ontology</td>
                </tr>

                <tr>
                  <td>confidence</td>
                  <td>The confidence score for this object</td>
                  <td>A confidence score of 1 is given for all labels created manually. More info can be found [here](/platform-documentation/Annotate/annotate-label-editor#confidence-score)</td>
                </tr>

                <tr>
                  <td>frame</td>
                  <td>The frame number of the data unit where the label appears</td>
                  <td>A frame number of 0 represents the first frame of the data unit. Images always have a frame number of 0. </td>
                </tr>

                <tr>
                  <td>createdBy</td>
                  <td>The email of the user that created this object</td>

                  <td />
                </tr>

                <tr>
                  <td>createdAt</td>
                  <td>Date and time the object was created</td>

                  <td />
                </tr>

                <tr>
                  <td>lastEditedBy</td>
                  <td>The email of the user that last edited this object</td>

                  <td />
                </tr>

                <tr>
                  <td>lastEditedAt</td>
                  <td>Date and time the object was last edited</td>

                  <td />
                </tr>

                <tr>
                  <td>manualAnnotation</td>
                  <td>A field indicating whether the object was drawn manually or not</td>
                  <td>`true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique</td>
                </tr>

                <tr>
                  <td>boundingBox</td>
                  <td>A list containing the coordinates for the bounding box</td>
                  <td>Refer to the [Ontology shapes](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) section for more details</td>
                </tr>
              </tbody>
            </table>
          </Accordion>

          <Accordion title="classifications">
            `classifications` contains all classification information for the image.

            The following example shows a single object instance.

            ```json theme={"dark"}
            "classifications": [
              {
                    "name": "Time of day",
                    "value": "time_of_day",
                    "createdAt":"Tue, 10 Oct 2023 14:16:14 GMT",
                    "createdBy": "david.babuschkin@encord.com",
                    "confidence": "1",
                    "featureHash": "wUS7p9B6",
                    "lastEditedAt": "Tue, 10 Oct 2023 14:16:14 GMT",
                    "classificationHash": "jiOiEq76",
                    "manualAnnotation": true
                  }
            ]  
            ```

            | **Key**            | **Description**                                                 | **Notes**                                                                                                                                                                      |   |
            | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - |
            | name               | The classification's name                                       | As specified in the ontology                                                                                                                                                   |   |
            | value              | The classification value                                        | Same as the `name`                                                                                                                                                             |   |
            | createdAt          | Time and day the classification  was created                    |                                                                                                                                                                                |   |
            | createdBy          | The email of the user that created this classification          |                                                                                                                                                                                |   |
            | confidence         | The confidence score for this classification                    | A confidence score of 1 is given for all labels created manually. More info can be found [here](/platform-documentation/Annotate/annotate-label-editor#confidence-score)       |   |
            | featureHash        | The classification instance hash                                | Corresponds to the FeatureNodeHash in the Ontology                                                                                                                             |   |
            | lastEditedAt       | Time and date of the last time this classification was edited   |                                                                                                                                                                                |   |
            | classificationHash | The classification instance  hash   hash                        |                                                                                                                                                                                |   |
            | manualAnnotation   | A field indicating whether the object was drawn manually or not | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |   |
          </Accordion>
        </AccordionGroup>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="object_answers">
    `object_answers` is a list of objects that have at least one nested attribute and contains information for all attributes. Expanding `object_answers` reveals the following:

    ```json theme={"dark"}
    "object_answers": {
      "Gqh06ypx"
          "objectHash": "Gqh06ypx",
          "classifications" [ 
            "name": "Size",
            "value": "size",
            "answers": "Medium",
            "featureHash": "GZnFumFq",
            "manualAnnotation": true
          ]
    }  
    ```

    | **Key**          | **Description**                                                                                     | **Notes**                                                                                                                                                                      |
    | ---------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | objectHash       | The hash of the object containing the attributes                                                    | The 'hash' represents a unique identifier                                                                                                                                      |
    | classifications  | A list of attributes related to the object. Includes *Dynamic* attributes and *Relation* attributes | Not to be confused with classifications as defined in our glossary, which apply to a frame                                                                                     |
    | name             | The attribute name                                                                                  |                                                                                                                                                                                |
    | value            | The attribute value                                                                                 | Always the same as the name                                                                                                                                                    |
    | answers          | The value(s) the attribute(s) were set to                                                           | If the attribute was a radio button, the answer is the option selected by the annotator                                                                                        |
    | featureHash      | The attribute's hash                                                                                | The 'hash' represents a unique identifier                                                                                                                                      |
    | manualAnnotation | A field indicating whether the object was drawn manually or not                                     | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
  </Accordion>

  <Accordion title="classification_answers">
    Contains a list of classifications that apply to entire frames or slices. `classification_answer` is represented by its hash. Expanding `classification_answers` reveals the following:

    ```json theme={"dark"}
    "classification_answers": {
      "OFX2jzwE": {
        "classificationHash": "OFX2jzwE", 
        "classifications": [{
          "name": "Time of day", 
          "value": "time_of_day", 
          "answers": [{
            "name": "Night", 
            "value": "night", 
            "featureHash": "j/7dpSmi"}],    
        "featureHash": "uZmB5YZC", 
        "manualAnnotation": true
        }]
      }
    }
    ```

    | **Key**            | **Description**                                                                                           | **Notes**                                                     |
    | ------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
    | classificationHash | The classification's hash                                                                                 | Corresponds to the featureNodeHash in the Ontology            |
    | classifications    | A list of classification information                                                                      |                                                               |
    | name               | The classification name                                                                                   | As set in the Ontology  (Quality in the example above)        |
    | value              | The classification value                                                                                  | Always the same as the classification name                    |
    | answers            | A list of all classification answers                                                                      | "answers" refer to the values the classification were set to. |
    | name               | The name of the classification answer                                                                     | "Night" in the example above                                  |
    | value              | The classification answer's value                                                                         | Always the same as the classifications answer's name          |
    | featureHash        | The hash for the particular classification answer                                                         | Included in `answers`                                         |
    | featureHash        | The hash for the particular classification                                                                |                                                               |
    | manualAnnotation   | "true" for all manually created labels. "false" for all labels created with automated labeling techniques |                                                               |
  </Accordion>

  <Accordion title="export_history">
    The `export_history` contains a list of all exports for this data unit, the first entry being the current export. Each instance contains the following:

    ```json theme={"dark"}
    "export_history": {
      "0"
          "export_hash": "Gqh06ypx",
          "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
          "user_email": "david.babuschkin@encord.com"
    }  
    ```

    | **Key**      | **Description**                             | **Notes**                                 |
    | ------------ | ------------------------------------------- | ----------------------------------------- |
    | export\_hash | The export instance's hash                  | The 'hash' represents a unique identifier |
    | exported\_at | Date and time of the export                 |                                           |
    | user\_email  | The email of the user that made this export |                                           |
  </Accordion>
</AccordionGroup>

***

### Image Groups & Image Sequences

The export contains a list of JSON objects, with each JSON object representing a single image group or image sequence, and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.

```json theme={"dark"}
[
  {
    "label_hash": "781dd0ff-e4c2-48f1-bcd1-09f2f0756701",
    "created_at": "2023-03-23 11:42:14",
    "last_edited_at": "2023-10-02 13:53:03",
    "dataset_hash": "4a4141ed-8d8b-4518-b1f7-97a5c53e992b",
    "dataset_title": "cooking_image_sequences",
    "data_title": "image-group-67bdc95d",
    "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
    "data_type": "image_group",
    "is_image_sequence": null,
    "image_sequence_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
    "data_units": { },
    "classification_answers": { },
    "object_actions": { },
    "label_status": "LABELLED",
    "export_history": [
      {
        "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
        "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
        "user_email": "david.babuschkin@encord.com"
      },
      {
        "export_hash": "2e0ee531-41ce-4ce9-a859-b6b47697e5d2",
        "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
        "user_email": "david.babuschkin@encord.com"
      }
    ],
    "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
    "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
  }
]
```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| data\_type              | The data unit's file format                                                                                                                        | Always "img\_group" for image groups and image sequences                                                                                 |
| is\_image\_sequence     | `true` when the data unit is an image sequence                                                                                                     | `false` for all other types of data, including image groups. This is what distinguishes image groups and image sequences in your export  |
| video\_link             | Contains a link to file storage location if file is a video                                                                                        | Always "null" for image groups and image sequences                                                                                       |
| data\_units             | List of all files the data unit is composed of                                                                                                     | Details of the export information for data units can be found below.                                                                     |
| object\_answers         | All the attributes in this data unit                                                                                                               | The object attributes are identified using their hash                                                                                    |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled.                                                                                                  |                                                                                                                                          |
| export\_history         | Contains a record of the export history for this data unit                                                                                         | Exporting labels to confirm export history generates an export history entry.                                                            |
| export\_hash            | The hash for this particular export instance                                                                                                       | The 'hash' represents a unique identifier                                                                                                |
| exported\_at            | The date and time when a particular export instance took place.                                                                                    |                                                                                                                                          |

***

<AccordionGroup>
  <Accordion title="data_units">
    The `data_units` key contains a list of all files that compose the image group or image sequence (sometimes referred to as frames). It contains the following information.

    <Warning>`data_units` here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.</Warning>

    ```json theme={"dark"}

    "data_units": {
          "9c588f63-ad87-4987-a074-06ba0d6980cd": {
            "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
            "data_title": "rhein-hafen.jpg4",
            "data_type": "image/jpg",
            "data_sequence": 0,
            "labels": { },
            "data_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
            "width": 512,
            "height": 512
          }
    }  
    ```

    | **Key**        | **Description**                                                                         | **Notes**                                           |
    | -------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------- |
    | data\_hash     | The file's hash                                                                         | The 'hash' represents a unique identifier           |
    | data\_title    | The file's title                                                                        |                                                     |
    | data\_type     | The file type                                                                           |                                                     |
    | data\_sequence | The sequence number of this file within the data unit                                   | 0 represents the first file                         |
    | labels         | A list of all frames contained in image group or sequence, and any labels on each frame | This contains the label information for each frame. |
    | width          | The width of the frame in pixel (px)                                                    |                                                     |
    | height         | The height of the frame in pixel (px)                                                   |                                                     |

    <AccordionGroup>
      <Accordion title="labels">
        Each number within `labels` represents an individual frame within the image group or sequence. Each frame contains the following:

        ```json theme={"dark"}

        "labels": {
              "0": {
                "objects": { },
                "classifications": [ ],
                "metadata":{ }
              }
        }  
        ```

        | **Key**         | **Description**                                        | **Notes**                                                   |
        | --------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
        | objects         | A list of label objects in this frame                  | Contains geometric information for object labels            |
        | classifications | A list of classifications applying to the entire frame | Is the same value for all instances of this classification. |

        <AccordionGroup>
          <Accordion title="objects">
            `objects` contains label information for all object instances in a frame. A key with the name of the object shape is always present - `bounding_box` in the example below. All shapes contain coordinates for each vertex.

            <Tip>Navigate to the [Ontology shapes section](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) to see how all Ontology classes are represented in the exported file.</Tip>

            The example below shows a single object instance.

            ```json theme={"dark"}
            "objects": [
                  {
                    "name": "Apple",
                    "color": "#D33115",
                    "shape":"bounding_box",
                    "value": "apple",
                    "boundingBox": {
                      "0": {
                        "h": 0.3235,
                        "w": 0.1697,
                        "x": 0.0153,
                        "y": 0.254,   
                      }
                    },
                    "createdAt": "Thu, 07 Sep 2023 09:47:35 GMT",
                    "createdBy": "david.babuschkin@encord.com",
                    "confidence": "1",
                    "objectHash": "P6gqJT/3",
                    "featureHash": "jiOiEq76",
                    "manualAnnotation": true
                  }
            ]  
            ```

            | **Key**          | **Description**                                                 | **Notes**                                                                                                                                                                      |
            | ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
            | name             | The object's name                                               | As specified in the ontology                                                                                                                                                   |
            | color            | The color used to draw the object                               | As specified in the ontology                                                                                                                                                   |
            | shape            | The Ontology class used to create the object                    | As specified in the ontology                                                                                                                                                   |
            | value            | The name given to the object                                    |                                                                                                                                                                                |
            | createdAt        | Date and time the object was created                            |                                                                                                                                                                                |
            | createdBy        | The email of the user that created this object                  |                                                                                                                                                                                |
            | confidence       | The confidence score for this object                            | A confidence score of 1 is given for all labels created manually. More info can be found [here](/platform-documentation/Annotate/annotate-label-editor#confidence-score)       |
            | objectHash       | The specific label's hash                                       | The 'hash' represents a unique identifier                                                                                                                                      |
            | featureHash      | The Ontology object's hash                                      | Corresponds to the FeatureNodeHash in the ontology                                                                                                                             |
            | manualAnnotation | A field indicating whether the object was drawn manually or not | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
            | boundingBox      | A list containing the coordinates for the bounding box          | Refer to the [Ontology shapes](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) section for more details                                 |
          </Accordion>

          <Accordion title="classifications">
            `classifications` contains all frame level classification information for the image group or sequence.

            The example below shows a single classification instance.

            ```json theme={"dark"}
            "classifications": [
                  {
                    "name": "Time of day",
                    "value": "time_of_day",
                    "createdAt":"Tue, 10 Oct 2023 14:16:14 GMT",
                    "createdBy": "david.babuschkin@encord.com",
                    "confidence": "1",
                    "featureHash": "wUS7p9B6",
                    "lastEditedAt": "Tue, 10 Oct 2023 14:16:14 GMT",
                    "classificationHash": "jiOiEq76",
                    "manualAnnotation": true
                  }
            ]  
            ```

            | **Key**            | **Description**                                                 | **Notes**                                                                                                                                                                      |   |
            | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - |
            | name               | The classification's name                                       | As specified in the ontology                                                                                                                                                   |   |
            | value              | The classification value                                        | Same as the `name`                                                                                                                                                             |   |
            | createdAt          | Time and day the classification  was created                    |                                                                                                                                                                                |   |
            | createdBy          | The email of the user that created this classification          |                                                                                                                                                                                |   |
            | confidence         | The confidence score for this classification                    | A confidence score of 1 is given for all labels created manually. More info can be found [here](/platform-documentation/Annotate/annotate-label-editor#confidence-score)       |   |
            | featureHash        | The classification instance hash                                | Corresponds to the FeatureNodeHash in the Ontology                                                                                                                             |   |
            | lastEditedAt       | Time and date of the last time this classification was edited   |                                                                                                                                                                                |   |
            | classificationHash | The classification instance  hash   hash                        |                                                                                                                                                                                |   |
            | manualAnnotation   | A field indicating whether the object was drawn manually or not | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |   |
          </Accordion>
        </AccordionGroup>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="object_answers">
    `object_answers` is a list of objects that have at least one nested attribute and contains information for all attributes. Expanding `object_answers` reveals the following:

    ```json theme={"dark"}
    "object_answers": {
      "Gqh06ypx"
          "objectHash": "Gqh06ypx",
          "classifications" [{ 
            "name": "Size",
            "value": "size",
            "answers": "Medium",
            "featureHash": "GZnFumFq",
            "manualAnnotation": true
      }]
    }  
    ```

    | **Key**          | **Description**                                                                                     | **Notes**                                                                                                                                                                      |
    | ---------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | objectHash       | The hash of the object containing the attributes                                                    | The 'hash' represents a unique identifier                                                                                                                                      |
    | classifications  | A list of attributes related to the object. Includes *Dynamic* attributes and *Relation* attributes | Not to be confused with classifications as defined in our glossary, which apply to a frame                                                                                     |
    | name             | The attribute name                                                                                  |                                                                                                                                                                                |
    | value            | The attribute value                                                                                 | Always the same as the name                                                                                                                                                    |
    | answers          | The value(s) the attribute(s) were set to                                                           | If the attribute was a radio button, the answer is the option selected by the annotator                                                                                        |
    | featureHash      | The attribute's hash                                                                                | The 'hash' represents a unique identifier                                                                                                                                      |
    | manualAnnotation | A field indicating whether the object was drawn manually or not                                     | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
  </Accordion>

  <Accordion title="classification_answers">
    Contains a list of classifications that apply to entire frames or slices. `classification_answer` is represented by its hash. Expanding `classification_answers` reveals the following:

    ```json theme={"dark"}
    "classification_answers": {
      "OFX2jzwE": {
        "classificationHash": "OFX2jzwE", 
        "classifications": [{
          "name": "Quality", 
          "value": "quality", 
          "answers": [{
            "name": "out of focus", 
            "value": "out_of_focus", 
            "featureHash": "j/7dpSmi"}],    
        "featureHash": "uZmB5YZC", 
        "manualAnnotation": true
        }]
      }
    }
    ```

    | **Key**            | **Description**                                                                                           | **Notes**                                                      |
    | ------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
    | classificationHash | The classification's hash                                                                                 | The 'hash' represents a unique identifier                      |
    | classifications    | A list of classifications information                                                                     |                                                                |
    | name               | The classification name                                                                                   | As set in the Ontology  (Quality in the example above)         |
    | value              | The classification value                                                                                  | Always the same as the classification name                     |
    | answers            | A list of all classification answers                                                                      | "answers" refer to the values the classifications were set to. |
    | name               | The name of the classification answer                                                                     | "out of focus" in the example above                            |
    | value              | The classification answer's value                                                                         | Always the same as the classification answer's name            |
    | featureHash        | The hash for the particular classification answer                                                         | Included in `answers`                                          |
    | featureHash        | The hash for the particular classification                                                                |                                                                |
    | manualAnnotation   | "true" for all manually created labels. "false" for all labels created with automated labeling techniques |                                                                |
  </Accordion>

  <Accordion title="export_history">
    The `export_history` contains a list of all exports for this data unit, the first entry being the current export. Each instance contains the following:

    ```json theme={"dark"}
    "export_history": {
      "0"
          "export_hash": "Gqh06ypx",
          "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
          "user_email": "david.babuschkin@encord.com"
    }  
    ```

    | **Key**      | **Description**                             | **Notes**                                 |
    | ------------ | ------------------------------------------- | ----------------------------------------- |
    | export\_hash | The export instance's hash                  | The 'hash' represents a unique identifier |
    | exported\_at | Date and time of the export                 |                                           |
    | user\_email  | The email of the user that made this export |                                           |
  </Accordion>
</AccordionGroup>

***

### Videos

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.

```json theme={"dark"}

[
  {
    "label_hash": "781dd0ff-e4c2-48f1-bcd1-09f2f0756701",
    "created_at": "2023-03-23 11:42:14",
    "last_edited_at": "2023-10-02 13:53:03",
    "dataset_hash": "4a4141ed-8d8b-4518-b1f7-97a5c53e992b",
    "dataset_title": "cooking_videos",
    "data_title": "how-to-make-apple-pie.mp4",
    "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
    "data_type": "video",
    "is_image_sequence": null,
    "video_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
    "data_units": { },
    "classification_answers": { },
    "object_actions": { },
    "label_status": "LABELLED",
    "export_history": [
      {
        "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
        "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
        "user_email": "david.babuschkin@encord.com"
      },
      {
        "export_hash": "2e0ee531-41ce-4ce9-a859-b6b47697e5d2",
        "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
        "user_email": "david.babuschkin@encord.com"
      }
    ],
    "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
    "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
  }
]

```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The Dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| data\_type              | The data unit's file format                                                                                                                        | Always "video" for videos                                                                                                                |
| is\_image\_sequence     | "true" when the data unit is an image sequence                                                                                                     | Always "null" for videos                                                                                                                 |
| video\_link             | Link to the video saved on your private cloud                                                                                                      | Always "null" for all other file types                                                                                                   |
| data\_units             | List of all files the data unit is composed of                                                                                                     | Details of the export information for \`data\_units\`\` can be found below.                                                              |
| object\_answers         | All the attributes in this data unit                                                                                                               | The object attributes are identified using their hash                                                                                    |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled.                                                                                                  |                                                                                                                                          |
| export\_history         | Contains a record of the export history for this data unit                                                                                         | Exporting labels to confirm export history generates an export history entry.                                                            |
| export\_hash            | The hash for this particular export instance                                                                                                       | The 'hash' represents a unique identifier                                                                                                |
| exported\_at            | The date and time when a particular export instance took place.                                                                                    |                                                                                                                                          |

***

<AccordionGroup>
  <Accordion title="data_units">
    The `data_units` key contains all files that compose the data unit. For a given video there is only a single element in this list. This element contains the following information.

    <Warning>`data_units` here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data unit elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.</Warning>

    ```json theme={"dark"}

    "data_units": {
          "9c588f63-ad87-4987-a074-06ba0d6980cd": {
            "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
            "data_title": "how-to-make-apple-pie.mp4",
            "data_type": "video/mp4",
            "data_sequence": 0,
            "labels": { },
            "data_fps": "23.976023976023978" ,
            "data_duration": "29.0786",
            "data_link": "www.my-private-cloud.com/how-to-make-apple-pie.mp4",
            "width": 512,
            "height": 512
          }
    }  
    ```

    | **Key**        | **Description**                                                          | **Notes**                                           |
    | -------------- | ------------------------------------------------------------------------ | --------------------------------------------------- |
    | data\_hash     | The file's hash                                                          | The 'hash' represents a unique identifier           |
    | data\_title    | The file's title                                                         |                                                     |
    | data\_type     | The file type                                                            |                                                     |
    | data\_sequence | The sequence number of this file within the data unit                    | 0 represents the first file                         |
    | labels         | A list of all frames contained in the video and any labels on each frame | This contains the label information for each frame. |
    | data\_fps      | The frames per second for this video                                     |                                                     |
    | data\_duration | The video length                                                         | In seconds                                          |
    | data\_link     | A link to the file stored in your private cloud                          |                                                     |
    | width          | The width of the frame in pixel (px)                                     |                                                     |
    | height         | The height of the frame in pixel (px)                                    |                                                     |

    <AccordionGroup>
      <Accordion title="labels">
        Each number within `labels` represents an individual frame within the data unit. Each frame contains the following:

        ```json theme={"dark"}

        "labels": {
              "0": {
                "objects": { },
                "classifications": [ ],
                "metadata":{ }
              }
        }  
        ```

        | **Key**         | **Description**                                        | **Notes**                                                   |
        | --------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
        | objects         | A list of label objects in this frame                  | Contains geometric information for object labels            |
        | classifications | A list of classifications applying to the entire frame | Is the same value for all instances of this classification. |

        <AccordionGroup>
          <Accordion title="objects">
            `objects` contains label information for all object instances in a frame. A key with the name of the object shape is always present - `bounding_box` in the example below. All shapes contain coordinates for each vertex.

            <Tip>Navigate to the [Ontology shapes section](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) to see how all Ontology classes are represented in the exported file.</Tip>

            The following example shows a single object instance.

            ```json theme={"dark"}
            "objects": [
              {
                    "name": "Apple",
                    "color": "#D33115",
                    "shape":"bounding_box",
                    "value": "apple",
                    "boundingBox": {
                      "0": {
                        "h": 0.3235,
                        "w": 0.1697,
                        "x": 0.0153,
                        "y": 0.254,   
                      }
                    },
                    "createdAt": "Thu, 07 Sep 2023 09:47:35 GMT",
                    "createdBy": "david.babuschkin@encord.com",
                    "confidence": "1",
                    "objectHash": "P6gqJT/3",
                    "featureHash": "jiOiEq76",
                    "manualAnnotation": true
                  }
            ]  
            ```

            | **Key**          | **Description**                                                 | **Notes**                                                                                                                                                                      |
            | ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
            | name             | The object's name                                               | As specified in the ontology                                                                                                                                                   |
            | color            | The color used to draw the object                               | As specified in the ontology                                                                                                                                                   |
            | shape            | The ontology class used to create the object                    | As specified in the ontology                                                                                                                                                   |
            | value            | The name given to the object                                    |                                                                                                                                                                                |
            | createdAt        | Date and time the object was created                            |                                                                                                                                                                                |
            | createdBy        | The email of the user that created this object                  |                                                                                                                                                                                |
            | confidence       | The confidence score for this object                            | A confidence score of 1 is given for all labels created manually. More info can be found [here](/platform-documentation/Annotate/annotate-label-editor#confidence-score)       |
            | objectHash       | The specific label's hash                                       | The 'hash' represents a unique identifier                                                                                                                                      |
            | featureHash      | The Ontology object's hash                                      | Corresponds to the FeatureNodeHash in the ontology                                                                                                                             |
            | manualAnnotation | A field indicating whether the object was drawn manually or not | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
            | boundingBox      | A list containing the coordinates for the bounding box          | Refer to the [Ontology shapes](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) section for more details                                 |
          </Accordion>

          <Accordion title="classifications">
            `classifications` contains all frame level classification information for the video.

            The example below shows a single classification instance.

            ```json theme={"dark"}
            "classifications": [
              {
                    "name": "Time of day",
                    "value": "time_of_day",
                    "createdAt":"Tue, 10 Oct 2023 14:16:14 GMT",
                    "createdBy": "david.babuschkin@encord.com",
                    "confidence": "1",
                    "featureHash": "wUS7p9B6",
                    "lastEditedAt": "Tue, 10 Oct 2023 14:16:14 GMT",
                    "classificationHash": "jiOiEq76",
                    "manualAnnotation": true
                  }
            ]  
            ```

            | **Key**            | **Description**                                                 | **Notes**                                                                                                                                                                      |   |
            | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - |
            | name               | The classification's name                                       | As specified in the ontology                                                                                                                                                   |   |
            | value              | The classification value                                        | Same as the `name`                                                                                                                                                             |   |
            | createdAt          | Time and day the classification  was created                    |                                                                                                                                                                                |   |
            | createdBy          | The email of the user that created this classification          |                                                                                                                                                                                |   |
            | confidence         | The confidence score for this classification                    | A confidence score of 1 is given for all labels created manually. More info can be found [here](/platform-documentation/Annotate/annotate-label-editor#confidence-score)       |   |
            | featureHash        | The classification instance hash                                | Corresponds to the FeatureNodeHash in the Ontology                                                                                                                             |   |
            | lastEditedAt       | Time and date of the last time this classification was edited   |                                                                                                                                                                                |   |
            | classificationHash | The classification instance  hash   hash                        |                                                                                                                                                                                |   |
            | manualAnnotation   | A field indicating whether the object was drawn manually or not | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |   |
          </Accordion>
        </AccordionGroup>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="object_answers">
    `object_answers` is a list of objects that have at least one nested attribute and contains information for all attributes. Expanding `object_answers` reveals the following:

    ```json theme={"dark"}
    "object_answers": {
      "Gqh06ypx"
          "objectHash": "Gqh06ypx",
          "classifications" [ 
            "name": "Size",
            "value": "size",
            "answers": "Medium",
            "featureHash": "GZnFumFq",
            "manualAnnotation": true
          ]
    }  
    ```

    | **Key**          | **Description**                                                 | **Notes**                                                                                                                                                                      |
    | ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | objectHash       | The hash of the object containing the attributes                | The 'hash' represents a unique identifier                                                                                                                                      |
    | classifications  | A list of attributes related to the object                      | Not to be confused with classifications as defined in our glossary, which apply to a frame                                                                                     |
    | name             | The attribute name                                              |                                                                                                                                                                                |
    | value            | The attribute value                                             | Always the same as the name                                                                                                                                                    |
    | answers          | The value(s) the attribute(s) were set to                       | If the attribute was a radio button, the answer is the option selected by the annotator                                                                                        |
    | featureHash      | The attribute's hash                                            | The 'hash' represents a unique identifier                                                                                                                                      |
    | manualAnnotation | A field indicating whether the object was drawn manually or not | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
  </Accordion>

  <Accordion title="classification_answers">
    Contains a list of classifications that apply to entire frames or slices. `classification_answer` is represented by its hash. Expanding `classification_answers` reveals the following:

    ```json theme={"dark"}
    "classification_answers": {
      "OFX2jzwE": {
        "classificationHash": "OFX2jzwE", 
        "classifications": [{
          "name": "Quality", 
          "value": "quality", 
          "answers": [{
            "name": "out of focus", 
            "value": "out_of_focus", 
            "featureHash": "j/7dpSmi"}],    
        "featureHash": "uZmB5YZC", 
        "manualAnnotation": true
        }]
      }
    }
    ```

    | **Key**            | **Description**                                                                                           | **Notes**                                                      |
    | ------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
    | classificationHash | The classification's hash                                                                                 | The 'hash' represents a unique identifier                      |
    | classifications    | A list of classifications information                                                                     |                                                                |
    | name               | The classification name                                                                                   | As set in the ontology  (Quality in the example above)         |
    | value              | The classification value                                                                                  | Always the same as the classification name                     |
    | answers            | A list of all classification answers                                                                      | "answers" refer to the values the classifications were set to. |
    | name               | The name of the classification answer                                                                     | "out of focus" in the example above                            |
    | value              | The classification answer's value                                                                         | Always the same as the classification answer's name            |
    | featureHash        | The hash for the particular classification answer                                                         | Included in `answers`                                          |
    | featureHash        | The hash for the particular classification                                                                |                                                                |
    | manualAnnotation   | "true" for all manually created labels. "false" for all labels created with automated labeling techniques |                                                                |
  </Accordion>

  <Accordion title="export_history">
    The `export_history` contains a list of all exports for this data unit, the first entry being the current export. Each instance contains the following:

    ```json theme={"dark"}
    "export_history": {
      "0"
          "export_hash": "Gqh06ypx",
          "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
          "user_email": "david.babuschkin@encord.com"
    }  
    ```

    | **Key**      | **Description**                             | **Notes**                                 |
    | ------------ | ------------------------------------------- | ----------------------------------------- |
    | export\_hash | The export instance's hash                  | The 'hash' represents a unique identifier |
    | exported\_at | Date and time of the export                 |                                           |
    | user\_email  | The email of the user that made this export |                                           |
  </Accordion>
</AccordionGroup>

***

### DICOM

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The following example describes all the keys for a single exported data unit.

```json theme={"dark"}

[
  {
    "label_hash": "781dd0ff-e4c2-48f1-bcd1-09f2f0756701",
    "created_at": "2023-03-23 11:42:14",
    "last_edited_at": "2023-10-02 13:53:03",
    "dataset_hash": "4a4141ed-8d8b-4518-b1f7-97a5c53e992b",
    "dataset_title": "BB: CT thin slices",
    "data_title": "9c58",
    "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
    "data_type": "dicom",
    "is_image_sequence": null,
    "video_link": null,
    "data_units": { },
    "classification_answers": { },
    "object_actions": { },
    "label_status": "LABELLED",
    "export_history": [
      {
        "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
        "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
        "user_email": "david.babuschkin@encord.com"
      },
      {
        "export_hash": "2e0ee531-41ce-4ce9-a859-b6b47697e5d2",
        "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
        "user_email": "david.babuschkin@encord.com"
      }
    ],
    "export_hash": "02b56519-9664-4e38-9713-4817a5caf648",
    "exported_at": "Mon, 02 Oct 2023 14:35:30 UTC",
  }
]

```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| data\_type              | The data unit's file format                                                                                                                        | Always "dicom" in a DICOM series                                                                                                         |
| is\_image\_sequence     | "true" when the data unit is an image sequence                                                                                                     | Always "null" for a DICOM series                                                                                                         |
| video\_link             | Link to the video or image sequence                                                                                                                | Always "null" for a DICOM series                                                                                                         |
| data\_units             | List of all files the data unit is composed of                                                                                                     | Details of the export information for \`data\_units\`\` can be found below.                                                              |
| object\_answers         | All the object attributes in this data unit                                                                                                        | The object attribute are identified using their hash                                                                                     |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled.                                                                                                  |                                                                                                                                          |
| export\_history         | Contains a record of the export history for the data unit                                                                                          | Exporting labels to confirm export history generates an export history entry.                                                            |
| export\_hash            | The hash for this particular export instance                                                                                                       | The 'hash' represents a unique identifier                                                                                                |
| exported\_at            | The date and time when a particular export instance took place.                                                                                    |                                                                                                                                          |

***

<AccordionGroup>
  <Accordion title="data_units">
    The `data_units` key contains all files that compose the data unit.

    <Warning>`data_units` here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.</Warning>

    ```json theme={"dark"}

    "data_units": {
          "9c588f63-ad87-4987-a074-06ba0d6980cd": {
            "data_hash": "9c588f63-ad87-4987-a074-06ba0d6980cd",
            "data_title": "9c58",
            "data_type": "application/dicom",
            "data_sequence": 0,
            "labels": { },
            "metadata": {  },
            "data_links": { },
            "width": 512,
            "height": 512
          }
    }  
    ```

    | **Key**        | **Description**                                                           | **Notes**                                                   |
    | -------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------- |
    | data\_hash     | The file's hash                                                           | The 'hash' represents a unique identifier                   |
    | data\_title    | The file's title                                                          |                                                             |
    | data\_type     | The file type                                                             |                                                             |
    | data\_sequence | The sequence number of this file within the data unit                     | 0 represents the first file                                 |
    | labels         | A list of all slices contained in the series and any labels on each slice | This contains the label information for each slice.         |
    | metadata       | The DICOM series metadata.                                                | Contains the ID for the patient, the study, and the series. |
    | data\_links    | Links to all slices within the series, ordered by their sequence number   |                                                             |
    | width          | The width of the slice in pixel (px)                                      |                                                             |
    | height         | The height of the slice in pixel (px)                                     |                                                             |

    <AccordionGroup>
      <Accordion title="labels">
        Each number within `labels` represents an individual slice or frame within the data unit. Each slice or frame contains the following:

        ```json theme={"dark"}

        "labels": {
              "0": {
                "objects": { },
                "classifications": [ ],
                "metadata":{ }
              }
        }  
        ```

        | **Key**         | **Description**                                                 | **Notes**                                                   |
        | --------------- | --------------------------------------------------------------- | ----------------------------------------------------------- |
        | objects         | A list of label objects on this slice                           | Contains geometric information for object labels            |
        | classifications | A list of classifications applying to the entire slice or frame | Is the same value for all instances of this classification. |
        | metadata        | Slice specific metadata                                         |                                                             |

        <AccordionGroup>
          <Accordion title="objects">
            `objects` contains label information for all object instances in a frame. A key with the name of the object shape is always present - `polygon` in the example below. All shapes contain coordinates for each vertex.

            <Tip>Navigate to the [Ontology shapes section](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) to see how all Ontology classes are represented in the exported file.</Tip>

            The example below shows a single object instance.

            ```json theme={"dark"}
            "objects": [
              {
                    "name": "lungs",
                    "color": "#D33115",
                    "shape":"polygon",
                    "value": "lungs",
                    "polygon": {
                      "0": {
                        "x": 0.2423,
                        "y": 0.5115,
                      },
                      "1": {
                        "x": 0.4167,
                        "y": 0.4218,   
                      }
                    },
                    "createdAt": "Thu, 07 Sep 2023 09:47:35 GMT",
                    "createdBy": "david.babuschkin@encord.com",
                    "confidence": "1",
                    "objectHash": "mQ+yKcF5",
                    "featureHash": "pRwpsg1H",
                    "manualAnnotation": true
                  }
            ]  
            ```

            | **Key**          | **Description**                                                         | **Notes**                                                                                                                                                                      |
            | ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
            | name             | The object's name                                                       | As specified in the ontology                                                                                                                                                   |
            | color            | The color used to draw the object                                       | As specified in the ontology                                                                                                                                                   |
            | shape            | The ontology class used to create the object                            | As specified in the ontology                                                                                                                                                   |
            | value            | The name given to the object                                            |                                                                                                                                                                                |
            | polygon          | A list containing the x and y coordinates of each vertex on the polygon | Refer to the [Ontology shapes](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) section for more details                                 |
            | createdAt        | Date and time the object was created                                    |                                                                                                                                                                                |
            | createdBy        | The email of the user that created this object                          |                                                                                                                                                                                |
            | confidence       | The confidence score for this object                                    | A confidence score of 1 is given for all labels created manually. More info can be found [here](/platform-documentation/Annotate/annotate-label-editor#confidence-score)       |
            | objectHash       | The specific label's hash                                               | The 'hash' represents a unique identifier                                                                                                                                      |
            | featureHash      | The ontology object's hash                                              | Corresponds to the FeatureNodeHash in the ontology                                                                                                                             |
            | manualAnnotation | A field indicating whether the object was drawn manually or not         | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
          </Accordion>

          <Accordion title="classifications">
            `classifications` contains all frame level classification  information for the slice.

            The example below shows a single classification instance.

            ```json theme={"dark"}
            "classifications": [
              {
                    "name": "State",
                    "value": "state",
                    "createdAt":"Tue, 10 Oct 2023 14:16:14 GMT",
                    "createdBy": "david.babuschkin@encord.com",
                    "confidence": "1",
                    "featureHash": "wUS7p9B6",
                    "lastEditedAt": "Tue, 10 Oct 2023 14:16:14 GMT",
                    "classificationHash": "jiOiEq76",
                    "manualAnnotation": true
                  }
            ]  
            ```

            | **Key**            | **Description**                                                 | **Notes**                                                                                                                                                                      |   |
            | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - |
            | name               | The classification's name                                       | As specified in the ontology                                                                                                                                                   |   |
            | value              | The classification value                                        | Same as the `name`                                                                                                                                                             |   |
            | createdAt          | Time and day the classification  was created                    |                                                                                                                                                                                |   |
            | createdBy          | The email of the user that created this classification          |                                                                                                                                                                                |   |
            | confidence         | The confidence score for this classification                    | A confidence score of 1 is given for all labels created manually. More info can be found [here](/platform-documentation/Annotate/annotate-label-editor#confidence-score)       |   |
            | featureHash        | The classification instance hash                                | Corresponds to the FeatureNodeHash in the ontology                                                                                                                             |   |
            | lastEditedAt       | Time and date of the last time this classification was edited   |                                                                                                                                                                                |   |
            | classificationHash | The classification instance  hash   hash                        |                                                                                                                                                                                |   |
            | manualAnnotation   | A field indicating whether the object was drawn manually or not | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |   |
          </Accordion>

          <Accordion title="metadata">
            ```json theme={"dark"}
            "metadata": {
                  "dicom_instance_uid": "1.3.9.1.4.7.14219.5.2.8.1600.1202.0357967439694942",
                  "multiframe_frame_number": "null",
                  "file_uri":"cord-dicoms/H7sLTXjYbrou3GhfmHRiuE5m92/5adba3dd-09f6-5c95-b954-e76542fe0ed7",
                  "width": "512",
                  "height": "512",
            }  
            ```

            | **Key**                   | **Description**                                                                  | **Notes**                                                                                                                                     |
            | ------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
            | dicom\_instance\_uid      | The DICOM instance UID                                                           | DICOM tag value (0008,0018). More information can be found [here](https://dicom.innolitics.com/ciods/rt-structure-set/sop-common/00080018)    |
            | multiframe\_frame\_number | A field indicating the frame number when the JSON contains only a single `label` | Displays `null` when each slice has its only expandable `labels` instance                                                                     |
            | file\_uri                 | This slice's URI                                                                 | Identifies this slice                                                                                                                         |
            | height                    | The slice's height (in pixel)                                                    | DICOM tag value (0028,0010). More information can be found [here](https://dicom.innolitics.com/ciods/rt-dose/general-image/00880200/00280010) |
            | width                     | The slice's width (in pixel)                                                     | DICOM tag value (0028,0011). More information can be found [here](https://dicom.innolitics.com/ciods/rt-dose/image-pixel/00280011)            |
          </Accordion>
        </AccordionGroup>
      </Accordion>

      <Accordion title="metadata">
        The slice metadata contains information on the DICOM study, the DICOM series, as well as the patient.

        ```json theme={"dark"}
        "metadata": {
              "patient_id": "ENC-ORD-LUV-031023",
              "study_uid": "null",
              "series_uid":"cord-dicoms/H7sLTXjYbrou3GhfmHRiuE5m92/5adba3dd-09f6-5c95-b954-e76542fe0ed7",
        }  
        ```

        | **Key**     | **Description**      | **Notes**                                                                                                                                       |
        | ----------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
        | patient\_id | The patient ID       | DICOM tag value (0010,0020). More information can be found [here](https://dicom.innolitics.com/ciods/rt-plan/patient/00101002/00100020)         |
        | study\_uid  | The DICOM study's ID | DICOM tag value (0020,000D). More information can be found [here](https://dicom.innolitics.com/ciods/mr-image/general-study/0020000d)           |
        | series\_uid | The DICOM series' ID | DICOM tag value (0020,000E). More information can be found [here](https://dicom.innolitics.com/ciods/mr-image/general-series/00081250/0020000e) |
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="object_answers">
    `object_answers` is a list of objects that have at least one nested attribute and contains information for all attributes. Expanding `object_answers` reveals the following:

    ```json theme={"dark"}
    "object_answers": {
      "Gqh06ypx"
          "objectHash": "Gqh06ypx",
          "classifications" [ 
            "name": "Size",
            "value": "size",
            "answers": "Medium",
            "featureHash": "GZnFumFq",
            "manualAnnotation": true
          ]
    }  
    ```

    | **Key**          | **Description**                                                                                      | **Notes**                                                                                                                                                                      |
    | ---------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | objectHash       | The hash of the object containing the attributes                                                     | The 'hash' represents a unique identifier                                                                                                                                      |
    | classifications  | A list of attributes related to the object. Includes *Dynamic* attributes and *Relation* attributes. | Not to be confused with classifications as defined in our glossary, which apply to a frame                                                                                     |
    | name             | The attribute name                                                                                   |                                                                                                                                                                                |
    | value            | The attribute value                                                                                  | Always the same as the name                                                                                                                                                    |
    | answers          | The value(s) the attribute(s) were set to                                                            | If the attribute was a radio button, the answer is the option selected by the annotator                                                                                        |
    | featureHash      | The attribute's hash                                                                                 | The 'hash' represents a unique identifier                                                                                                                                      |
    | manualAnnotation | A field indicating whether the object was drawn manually or not                                      | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
  </Accordion>

  <Accordion title="classification_answers">
    `classification_answers` a list of frame classifications in which each classification is represented by its hash. Expanding `classification_answers` reveals the following:

    ```json theme={"dark"}
    "classification_answers": {
      "OFX2jzwE": {
        "classificationHash": "OFX2jzwE", 
        "classifications": [{
          "name": "Quality", 
          "value": "quality", 
          "answers": [{
            "name": "out of focus", 
            "value": "out_of_focus", 
            "featureHash": "j/7dpSmi"}],    
        "featureHash": "uZmB5YZC", 
        "manualAnnotation": true
        }]
      }
    }
    ```

    | **Key**            | **Description**                                                                                           | **Notes**                                                     |
    | ------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
    | classificationHash | The classification's hash                                                                                 | The 'hash' represents a unique identifier                     |
    | classifications    | A list of information about the classification                                                            |                                                               |
    | name               | The classification name                                                                                   | As set in the ontology  (Quality in the example above)        |
    | value              | The classification value                                                                                  | Always the same as the classification name                    |
    | answers            | A list of all classification answers                                                                      | "answers" refer to the values the classification were set to. |
    | name               | The name of the classification answer                                                                     | "out of focus" in the example above                           |
    | value              | The classification answer's value                                                                         | Always the same as the classification answer's name           |
    | featureHash        | The hash for the particular classification answer                                                         | Included in `answers`                                         |
    | featureHash        | The hash for the particular classification                                                                |                                                               |
    | manualAnnotation   | `true` for all manually created labels. `false` for all labels created with automated labeling techniques |                                                               |
  </Accordion>

  <Accordion title="export_history">
    The `export_history` contains a list of all exports for this data unit, the first entry being the current export. Each instance contains the following:

    ```json theme={"dark"}
    "export_history": {
      "0"
          "export_hash": "Gqh06ypx",
          "exported_at": "Mon, 02 Oct 2023 13:47:45 UTC",
          "user_email": "david.babuschkin@encord.com"
    }  
    ```

    | **Key**      | **Description**                             | **Notes**                                 |
    | ------------ | ------------------------------------------- | ----------------------------------------- |
    | export\_hash | The export instance's hash                  | The 'hash' represents a unique identifier |
    | exported\_at | Date and time of the export                 |                                           |
    | user\_email  | The email of the user that made this export |                                           |
  </Accordion>
</AccordionGroup>

***

### Audio

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.

```json theme={"dark"}
[
    {
        "classification_answers": {},
        "created_at": "2025-01-09 15:58:20",
        "data_hash": "ffd810f4-f503-46ac-b54f-bd5f8057f440",
        "data_title": "beautiful-tune.mp3",
        "data_type": "audio",
        "data_units": {
        },
        "dataset_hash": "3696067a-7e68-4d25-b09d-517877e13f06",
        "dataset_title": "Music",
        "is_image_sequence": null,
        "is_valid": true,
        "label_hash": "a384bab6-9443-4932-a862-c5c18f39c88b",
        "label_status": "LABELLED",
        "last_edited_at": "2025-01-09 15:58:35",
        "object_actions": {},
        "object_answers": {}
    }
]
```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The Dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| data\_type              | The data unit's file format                                                                                                                        | Always "video" for videos                                                                                                                |
| is\_image\_sequence     | "true" when the data unit is an image sequence                                                                                                     | Always "null" for images                                                                                                                 |
| video\_link             | Contains a private cloud URL for videos                                                                                                            | Always "null" for images                                                                                                                 |
| data\_units             | List of all files the data unit is composed of                                                                                                     | Details of the export information for \`data\_units\`\` can be found below.                                                              |
| object\_answers         | All the attributes in this data unit                                                                                                               | The object attributes are identified using their hash                                                                                    |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled.                                                                                                  |                                                                                                                                          |
| export\_history         | Contains a record of the export history for this data unit                                                                                         | Exporting labels to confirm export history generates an export history entry.                                                            |
| export\_hash            | The hash for this particular export instance                                                                                                       | The 'hash' represents a unique identifier                                                                                                |
| exported\_at            | The date and time when a particular export instance took place.                                                                                    |                                                                                                                                          |

<AccordionGroup>
  <Accordion title="classification_answers">
    `classification_answers` a list of frame classifications in which each classification is represented by its hash. Expanding `classification_answers` reveals the following:

    ```json theme={"dark"}
    "classification_answers": {
        "yRY6RT5j": {
            "classificationHash": "yRY6RT5j",
            "classifications": [
                {
                    "answers": [
                        {
                            "featureHash": "h6dn9yfZ",
                            "name": "No ",
                            "value": "no_"
                        }
                    ],
                    "featureHash": "+n1+XoVr",
                    "manualAnnotation": true,
                    "name": "Good Song?",
                    "value": "good_song?"
                }
            ],
            "confidence": null,
            "createdAt": "Thu, 09 Jan 2025 15:58:27 GMT",
            "createdBy": "david.babuschkin@encord.com",
            "featureHash": "lQS4psvP",
            "lastEditedAt": "Thu, 09 Jan 2025 15:58:27 GMT",
            "lastEditedBy": "david.babuschkin@encord.com",
            "manualAnnotation": true,
            "range": [
                [
                    0,
                    132963
                ]
            ]
        }
    },
    ```

    | **Key**            | **Description**                                                                                           | **Notes**                                                     |
    | ------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
    | classificationHash | The classification's hash                                                                                 | The 'hash' represents a unique identifier                     |
    | classifications    | A list of information about the classification                                                            |                                                               |
    | name               | The classification name                                                                                   | As set in the ontology  (Quality in the example above)        |
    | value              | The classification value                                                                                  | Always the same as the classification name                    |
    | answers            | A list of all classification answers                                                                      | "answers" refer to the values the classification were set to. |
    | name               | The name of the classification answer                                                                     | "out of focus" in the example above                           |
    | value              | The classification answer's value                                                                         | Always the same as the classification answer's name           |
    | featureHash        | The hash for the particular classification answer                                                         | Included in `answers`                                         |
    | featureHash        | The hash for the particular classification                                                                |                                                               |
    | manualAnnotation   | `true` for all manually created labels. `false` for all labels created with automated labeling techniques |                                                               |
    | range              | The time span on which the classification label is applied                                                | Measured in milliseconds (ms)                                 |
  </Accordion>

  <Accordion title="data_units">
    The `data_units` key contains all files that compose the data unit. For a given image there is only ever a single element in this list. This element contains the following information.

    <Warning>`data_units` here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.</Warning>

    ```json theme={"dark"}
    "data_units": {
      "ffd810f4-f503-46ac-b54f-bd5f8057f440": {
          "audio_bit_depth": 32,
          "audio_codec": "mp3float",
          "audio_num_channels": 2,
          "audio_sample_rate": 44100,
          "data_duration": 132.96327,
          "data_hash": "ffd810f4-f503-46ac-b54f-bd5f8057f440",
          "data_link": "gs://cord-ai-platform.appspot.com/cord-audio-prod/iaDJxNNrMuQMtFPcP9oszw2OCHm2/6e235f70-8ade-4bb6-8d76-d3010d7deda3",
          "data_sequence": 0,
          "data_title": "beautiful-tune.mp3",
          "data_type": "audio/mpeg",
          "labels": {}
      }
    }
    ```

    | **Key**        | **Description**                                       | **Notes**                                                                           |
    | -------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
    | data\_hash     | The file's hash                                       | The 'hash' represents a unique identifier                                           |
    | data\_title    | The file's title                                      |                                                                                     |
    | data\_type     | The file type                                         |                                                                                     |
    | data\_sequence | The sequence number of this file within the data unit | Always `0` for images, as single images are composed of a single file by definition |
    | labels         | A container for the image's label information         | This contains the label information for the image.                                  |
    | data\_link     | A link to the file stored in your private cloud       |                                                                                     |
    | width          | The width of the image in pixel (px)                  |                                                                                     |
    | height         | The height of the image in pixel (px)                 |                                                                                     |
  </Accordion>

  <Accordion title="object_answers">
    `object_answers` contains all the object labels that have at least one nested attribute and contains information for all attributes. Expanding `object_answers` reveals the following:

    ```json theme={"dark"}
    "object_answers": {
        "zcmSZzvI": {
            "classifications": [],
            "confidence": null,
            "createdAt": "Thu, 09 Jan 2025 15:58:24 GMT",
            "createdBy": "david.babuschkin@encord.com",
            "featureHash": "1uLJrW4C",
            "lastEditedAt": "Thu, 09 Jan 2025 15:58:24 GMT",
            "lastEditedBy": "david.babuschkin@encord.com",
            "manualAnnotation": true,
            "objectHash": "zcmSZzvI",
            "range": [
                        [
                            14287,
                            51843
                        ]
            ]
        }
    }
    ```

    | **Key**          | **Description**                                                 | **Notes**                                                                                                                                                                      |
    | ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | objectHash       | The hash of the object containing the attributes                | The 'hash' represents a unique identifier                                                                                                                                      |
    | classifications  | A list of attributes related to the object.                     | Not to be confused with classifications as defined in our glossary, which apply to a frame                                                                                     |
    | name             | The attribute name                                              |                                                                                                                                                                                |
    | value            | The attribute value                                             | Always the same as the name                                                                                                                                                    |
    | answers          | The value(s) the attribute(s) were set to                       | If the attribute was a radio button, the answer is the option selected by the annotator                                                                                        |
    | featureHash      | The attribute's hash                                            | The 'hash' represents a unique identifier                                                                                                                                      |
    | manualAnnotation | A field indicating whether the object was drawn manually or not | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
    | range            | The time span on which the object label is applied              | Measured in milliseconds (ms)                                                                                                                                                  |
  </Accordion>
</AccordionGroup>

### Text

The export contains a list of JSON objects, with each JSON object representing a single data unit and containing detailed information for all exported labels.

The example below describes all the keys for a single exported data unit.

```json theme={"dark"}
[
    {
        "classification_answers": {},
        "created_at": "2025-01-11 14:58:20",
        "data_hash": "ffd810f4-f503-46ac-b54f-bd5f8057f440",
        "data_title": "encord-website.html",
        "data_type": "plain_text",
        "data_units": {
        },
        "dataset_hash": "3696067a-7e68-4d25-b09d-517877e13f06",
        "dataset_title": "HTML Text",
        "is_image_sequence": null,
        "is_valid": true,
        "label_hash": "a384bab6-9443-4932-a862-c5c18f39c88b",
        "label_status": "LABELLED",
        "last_edited_at": "2025-01-09 15:58:35",
        "object_actions": {},
        "object_answers": {}
    }
]
```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The Dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| data\_type              | The data unit's file format                                                                                                                        | Always "video" for videos                                                                                                                |
| is\_image\_sequence     | "true" when the data unit is an image sequence                                                                                                     | Always "null" for images                                                                                                                 |
| video\_link             | Contains a private cloud URL for videos                                                                                                            | Always "null" for images                                                                                                                 |
| data\_units             | List of all files the data unit is composed of                                                                                                     | Details of the export information for \`data\_units\`\` can be found below.                                                              |
| object\_answers         | All the attributes in this data unit                                                                                                               | The object attributes are identified using their hash                                                                                    |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled.                                                                                                  |                                                                                                                                          |
| export\_history         | Contains a record of the export history for this data unit                                                                                         | Exporting labels to confirm export history generates an export history entry.                                                            |
| export\_hash            | The hash for this particular export instance                                                                                                       | The 'hash' represents a unique identifier                                                                                                |
| exported\_at            | The date and time when a particular export instance took place.                                                                                    |                                                                                                                                          |

<AccordionGroup>
  <Accordion title="classification_answers">
    `classification_answers` a list of frame classifications in which each classification is represented by its hash. Expanding `classification_answers` reveals the following:

    ```json theme={"dark"}
    "classification_answers": {
        "EpcchMiS": {
            "classificationHash": "EpcchMiS",
            "classifications": [
                {
                    "answers": [
                        {
                            "featureHash": "4EbpTJ8E",
                            "name": "Single Extension",
                            "value": "single_extension"
                        }
                    ],
                    "featureHash": "/Kt0x2uF",
                    "manualAnnotation": true,
                    "name": "HTML Type",
                    "value": "html_type"
                }
            ],
            "confidence": null,
            "createdAt": "Tue, 07 Jan 2025 12:25:12 GMT",
            "createdBy": "david.babuschkin@encord.com",
            "featureHash": "yboRL9Pm",
            "lastEditedAt": "Tue, 07 Jan 2025 12:25:12 GMT",
            "lastEditedBy": "david.babuschkin@encord.com",
            "manualAnnotation": true,
            "range": [
                [
                    0,
                    0
                ]
            ]
        }
    }
    ```

    | **Key**            | **Description**                                                                                           | **Notes**                                                     |
    | ------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
    | classificationHash | The classification's hash                                                                                 | The 'hash' represents a unique identifier                     |
    | classifications    | A list of information about the classification                                                            |                                                               |
    | name               | The classification name                                                                                   | As set in the ontology  (Quality in the example above)        |
    | value              | The classification value                                                                                  | Always the same as the classification name                    |
    | answers            | A list of all classification answers                                                                      | "answers" refer to the values the classification were set to. |
    | name               | The name of the classification answer                                                                     | "out of focus" in the example above                           |
    | value              | The classification answer's value                                                                         | Always the same as the classification answer's name           |
    | featureHash        | The hash for the particular classification answer                                                         | Included in `answers`                                         |
    | featureHash        | The hash for the particular classification                                                                |                                                               |
    | manualAnnotation   | `true` for all manually created labels. `false` for all labels created with automated labeling techniques |                                                               |
    | range              | The frame range on which the classification label is applied                                              |                                                               |
  </Accordion>

  <Accordion title="data_units">
    The `data_units` key contains all files that compose the data unit. For a given image there is only ever a single element in this list. This element contains the following information.

    <Warning>`data_units` here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.</Warning>

    ```json theme={"dark"}
    "data_units": {
      "ffd810f4-f503-46ac-b54f-bd5f8057f440": {
          "audio_bit_depth": 32,
          "audio_codec": "mp3float",
          "audio_num_channels": 2,
          "audio_sample_rate": 44100,
          "data_duration": 132.96327,
          "data_hash": "ffd810f4-f503-46ac-b54f-bd5f8057f440",
          "data_link": "gs://cord-ai-platform.appspot.com/cord-audio-prod/iaDJxNNrMuQMtFPcP9oszw2OCHm2/6e235f70-8ade-4bb6-8d76-d3010d7deda3",
          "data_sequence": 0,
          "data_title": "beautiful-tune.mp3",
          "data_type": "audio/mpeg",
          "labels": {}
      }
    }
    ```

    | **Key**        | **Description**                                       | **Notes**                                                                           |
    | -------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
    | data\_hash     | The file's hash                                       | The 'hash' represents a unique identifier                                           |
    | data\_title    | The file's title                                      |                                                                                     |
    | data\_type     | The file type                                         |                                                                                     |
    | data\_sequence | The sequence number of this file within the data unit | Always `0` for images, as single images are composed of a single file by definition |
    | labels         | A container for the image's label information         | This contains the label information for the image.                                  |
    | data\_link     | A link to the file stored in your private cloud       |                                                                                     |
    | width          | The width of the image in pixel (px)                  |                                                                                     |
    | height         | The height of the image in pixel (px)                 |                                                                                     |
  </Accordion>

  <Accordion title="object_answers">
    `object_answers` contains all the object labels that have at least one nested attribute and contains information for all attributes. Expanding `object_answers` reveals the following:

    ```json theme={"dark"}
    "object_answers": {
        "YFfOG14v": {
            "classifications": [],
            "confidence": null,
            "createdAt": "Tue, 07 Jan 2025 12:25:36 GMT",
            "createdBy": "david.babuschkin@encord.com",
            "featureHash": "AZfKc9b7",
            "lastEditedAt": "Tue, 07 Jan 2025 12:25:36 GMT",
            "lastEditedBy": "david.babuschkin@encord.com",
            "manualAnnotation": true,
            "objectHash": "YFfOG14v",
            "range": [],
            "range_html": [
                {
                    "end": {
                        "node": "/html[1]/body[1]/div[1]/div[1]/div[1]/main[1]/div[2]/div[1]/section[1]/section[1]/article[1]/section[1]/section[1]/p[1]/text()[1]",
                        "offset": 245
                    },
                    "start": {
                        "node": "/html[1]/body[1]/div[1]/div[1]/div[1]/main[1]/div[2]/div[1]/section[1]/section[1]/article[1]/section[1]/section[1]/p[1]/text()[1]",
                        "offset": 125
                    }
                }
            ]
        }
    }
    ```

    | **Key**          | **Description**                                                                         | **Notes**                                                                                                                                                                      |
    | ---------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | objectHash       | The hash of the object containing the attributes                                        | The 'hash' represents a unique identifier                                                                                                                                      |
    | classifications  | A list of attributes related to the object.                                             | Not to be confused with classifications as defined in our glossary, which apply to a frame                                                                                     |
    | name             | The attribute name                                                                      |                                                                                                                                                                                |
    | value            | The attribute value                                                                     | Always the same as the name                                                                                                                                                    |
    | answers          | The value(s) the attribute(s) were set to                                               | If the attribute was a radio button, the answer is the option selected by the annotator                                                                                        |
    | featureHash      | The attribute's hash                                                                    | The 'hash' represents a unique identifier                                                                                                                                      |
    | manualAnnotation | A field indicating whether the object was drawn manually or not                         | `true` means it was drawn manually, while `false` means it was created using a model or an [automated labeling](/platform-documentation/Annotate/automated-labeling) technique |
    | range            | The frame range on which the object label is applied                                    |                                                                                                                                                                                |
    | range\_html      | Provides detailed information about the specific section of the text file being labeled |                                                                                                                                                                                |
    | start            | Start point of the label                                                                |                                                                                                                                                                                |
    | end              | End point of the label                                                                  |                                                                                                                                                                                |
    | offset           | An integer that specifies the character position within the identified node             | For example `{ "offset": 125 }` means the label starts / ends at the 125th character in the node                                                                               |
  </Accordion>
</AccordionGroup>

### PDF

```json theme={"dark"}
[
  {
    "label_hash": "f0159daf-a1c2-43e3-b516-633d5f3e513a",
    "created_at": "2025-08-28 08:32:24",
    "last_edited_at": "2025-11-18 11:56:16",
    "dataset_hash": "cbfa26a0-3608-473d-a8ae-aa40649aedc4",
    "dataset_title": "Documents",
    "data_title": "lyrics.pdf",
    "data_hash": "e7f7ce04-45b4-4645-af71-24d9159f32c2",
    "data_type": "application/pdf",
    "is_image_sequence": null,
    "video_link": null,
    "data_units": {},
    "classification_answers": {},
    "object_actions": {},
    "object_answers": {},
    "label_status": "LABEL_IN_PROGRESS",
    "export_history": [],
    "export_hash": null,
    "exported_at": null,
    "branch_name": "main",
    "backing_item_uuid": "d3b340a5-786d-44f6-b097-e569672c2948",
    "is_valid": true
  }
]
```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The Dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| data\_type              | The data unit's file format. In this case PCD scene                                                                                                | Always "video" for videos                                                                                                                |
| is\_image\_sequence     | "true" when the data unit is an image sequence                                                                                                     | Always "null" for images                                                                                                                 |
| video\_link             | Contains a private cloud URL for videos                                                                                                            | Always "null" for images                                                                                                                 |
| data\_units             | List of all files the data unit is composed of                                                                                                     | Details of the export information for \`data\_units\`\` can be found below.                                                              |
| object\_answers         | All the attributes in this data unit                                                                                                               | The object attributes are identified using their hash                                                                                    |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled.                                                                                                  |                                                                                                                                          |
| export\_history         | Contains a record of the export history for this data unit                                                                                         | Exporting labels to confirm export history generates an export history entry.                                                            |
| export\_hash            | The hash for this particular export instance                                                                                                       | The 'hash' represents a unique identifier                                                                                                |
| exported\_at            | The date and time when a particular export instance took place.                                                                                    |                                                                                                                                          |
| branch\_name            | The name of the branch the label is on                                                                                                             |                                                                                                                                          |
| backing\_item\_uuid     | The unique ID of the scene in Encord's storage on                                                                                                  |                                                                                                                                          |

<Accordion title="data_units">
  The `data_units` key contains all files that compose the data unit. For a given image there is only ever a single element in this list. This element contains the following information.

  <Warning>`data_units` here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.</Warning>

  ```json theme={"dark"}
  {
  "data_units": {
    "e7f7ce04-45b4-4645-af71-24d9159f32c2": {
      "data_hash": "e7f7ce04-45b4-4645-af71-24d9159f32c2",
      "data_title": "NeverGonnaGiveYouUp.pdf",
      "data_type": "",
      "data_sequence": 0,
      "labels": {}
    }
  }
  }
  ```

  | **Key**        | **Description**                                                                                                                                                                                       | **Notes**                                          |
  | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
  | data\_hash     | The file's hash                                                                                                                                                                                       | The 'hash' represents a unique identifier          |
  | data\_title    | The file's title                                                                                                                                                                                      |                                                    |
  | data\_type     | The file type                                                                                                                                                                                         |                                                    |
  | data\_sequence | The sequence number of this file within the data unit                                                                                                                                                 |                                                    |
  | labels         | A container for the image's label information. See the relevant [Ontology Shapes](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) section for more information | This contains the label information for the frame. |
</Accordion>

### PCD

```json theme={"dark"}
[
  {
    "label_hash": "f0159daf-a1c2-43e3-b516-633d5f3e513a",
    "created_at": "2025-08-28 08:32:24",
    "last_edited_at": "2025-11-18 11:56:16",
    "dataset_hash": "cbfa26a0-3608-473d-a8ae-aa40649aedc4",
    "dataset_title": "Nuscenes",
    "data_title": "scene-0553",
    "data_hash": "e7f7ce04-45b4-4645-af71-24d9159f32c2",
    "data_type": "scene",
    "is_image_sequence": null,
    "video_link": null,
    "data_units": {},
    "classification_answers": {},
    "object_actions": {},
    "object_answers": {},
    "label_status": "LABEL_IN_PROGRESS",
    "export_history": [],
    "export_hash": null,
    "exported_at": null,
    "branch_name": "main",
    "backing_item_uuid": "d3b340a5-786d-44f6-b097-e569672c2948",
    "is_valid": true
  }
]
```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The Dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| data\_type              | The data unit's file format. In this case PCD scene                                                                                                | Always "video" for videos                                                                                                                |
| is\_image\_sequence     | "true" when the data unit is an image sequence                                                                                                     | Always "null" for images                                                                                                                 |
| video\_link             | Contains a private cloud URL for videos                                                                                                            | Always "null" for images                                                                                                                 |
| data\_units             | List of all files the data unit is composed of                                                                                                     | Details of the export information for \`data\_units\`\` can be found below.                                                              |
| object\_answers         | All the attributes in this data unit                                                                                                               | The object attributes are identified using their hash                                                                                    |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled.                                                                                                  |                                                                                                                                          |
| export\_history         | Contains a record of the export history for this data unit                                                                                         | Exporting labels to confirm export history generates an export history entry.                                                            |
| export\_hash            | The hash for this particular export instance                                                                                                       | The 'hash' represents a unique identifier                                                                                                |
| exported\_at            | The date and time when a particular export instance took place.                                                                                    |                                                                                                                                          |
| branch\_name            | The name of the branch the label is on                                                                                                             |                                                                                                                                          |
| backing\_item\_uuid     | The unique ID of the scene in Encord's storage on                                                                                                  |                                                                                                                                          |

<Accordion title="data_units">
  The `data_units` key contains all files that compose the data unit. For a given image there is only ever a single element in this list. This element contains the following information.

  <Warning>`data_units` here refer to individual files that compose a data unit, as defined in our glossary, and are not to be confused with data units elsewhere in the platform. Encord will update this nomenclature soon, but we always communicate changes to all customers first.</Warning>

  ```json theme={"dark"}
  {
  "data_units": {
    "e7f7ce04-45b4-4645-af71-24d9159f32c2": {
      "data_hash": "e7f7ce04-45b4-4645-af71-24d9159f32c2",
      "data_title": "scene-0553",
      "data_type": "",
      "data_sequence": 0,
      "labels": {}
    }
  }
  }
  ```

  | **Key**        | **Description**                                                                                                                                                                                       | **Notes**                                          |
  | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
  | data\_hash     | The file's hash                                                                                                                                                                                       | The 'hash' represents a unique identifier          |
  | data\_title    | The file's title                                                                                                                                                                                      |                                                    |
  | data\_type     | The file type                                                                                                                                                                                         |                                                    |
  | data\_sequence | The sequence number of this file within the data unit                                                                                                                                                 |                                                    |
  | labels         | A container for the image's label information. See the relevant [Ontology Shapes](/platform-documentation/Annotate/annotate-export/annotate-export-json#ontology-shapes) section for more information | This contains the label information for the frame. |
</Accordion>

***

### Ontology Shapes

Exports contain the Ontology shape coordinates used to create the label.

<AccordionGroup>
  <Accordion title="Bounding Box">
    `x` and `y` represent coordinates of the top-left corner of the box. `h` and `w` respectively represent the height and width of the box.

    ```json theme={"dark"}
     "boundingBox": {
        "h": 0.118,
        "w": 0.1643,
        "x": 0.6985,
        "y": 0.6204
     }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Polygon">
    <Warning>
      This is a legacy field used by existing customers. We recommend new customers use the `polygons` field below.
    </Warning>

    The `polygon` list contains the `x` and `y` coordinates for all vertices in a simple polygon. For complex polygons, see the `polygons` field below.

    ```json theme={"dark"}
    "polygon": {
      "0": {
        "x": 0.2423,
        "y": 0.5115,
      },
      "1": {
        "x": 0.4167,
        "y": 0.4218,   
              },
      "2": {
        "x": 0.5821,
        "y": 0.4641,   
              },
      "3": {
        "x": 0.5808,
        "y": 0.5756,   
              },
      "4": {
        "x": 0.4564,
        "y": 0.6397,   
              }
      }

    ```
  </Accordion>

  <Accordion title="Polygons">
    Polygons can have complex shapes, including being enclosed in one another, and encompassing separate regions. In each case the polygon's coordinates are arranged in a different way.

    <div>
      <img />
    </div>

    <div>
      <img />
    </div>

    <div>
      <img />
    </div>

    <div>
      <img />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Polyline">
    Polylines contain the `x` and `y` coordinates for each vertex.

    ```json theme={"dark"}
     "polyline": {
      "0": {
        "x": 0.2423,
        "y": 0.5115,
      },
      "1": {
        "x": 0.4167,
        "y": 0.4218,   
              },
      "2": {
        "x": 0.5821,
        "y": 0.4641,   
              },
      "3": {
        "x": 0.5808,
        "y": 0.5756,   
              },
      "4": {
        "x": 0.4564,
        "y": 0.6397,   
              }
      }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Keypoint ">
    Keypoints are represented in the export using only `x` and `y` coordinates.

    ```json theme={"dark"}
     "point": {
        "0": {
          "x": 0.3192,
          "y": 0.1547,
      }
     }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Rotatable Bounding Box ">
    `x` and `y` represent the coordinates of the top-left corner of the *unrotated* box. `h` and `w` respectively represent the height and width of the box, while `theta` represents the angle of clockwise rotation of the bounding box *about the center of the box*.

    ```json theme={"dark"}
     "rotatableBoundingBox": {
        "h": 0.118,
        "w": 0.1643,
        "x": 0.6985,
        "y": 6204,
        "theta": 305.7762
     }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Bitmask ">
    The `rleString` encodes the Bitmask label, and has to be decoded. See our [SDK documentation](/sdk-documentation/sdk-labels/sdk-export#decode-bitmask-labels) to learn how to decode an `rleString`.

    ```json theme={"dark"}
    "objects": [
          {
            "bitmask": {
              "rleString": "02220N:0F20N",
              "top": 0,
              "left": 0,
              "width": 6,
              "height": 6
            }
          }
      ]  
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Object Primitive ">
    Object primitives are referred to as `skeleton`s in the export. Each point on the object primitive is represented in the export using `x` and `y` coordinates.

    Below is an example of an object primitive with 3 points.

    ```json theme={"dark"}
    "skeleton": {
      "0": {
        "x": 0.5719,
        "y": 0.7615,
        "name": "point_0",
        "color": "#fcc400",
        "value": "point_0",
        "featureHash": "qPCTeIci"
        },
        "1": {
        "x": 0.5428,
        "y": 0.6734,
        "name": "point_1",
        "color": "#fcc400",
        "value": "point_1",
        "featureHash": "o1NKWqKP",
        "invisible": true
        },
        "2": {
        "x": 0.4865,
        "y": 0.6464,
        "name": "point_2",
        "color": "#fcc400",
        "value": "point_2",
        "featureHash": "9bgJBA85",
        "occluded": true
        }
    }
    ```

    | Key         | Description                                             | Notes                                                                      |
    | ----------- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
    | name        | Name of this point                                      | As set in the Ontology                                                     |
    | color       | The hexadecimal color code used to represent this point | As set in the Ontology                                                     |
    | featureHash | The hash for this particular point                      | the 'hash' is a unique identifier                                          |
    | occluded    | This point is marked as occluded                        | if the point was left on the default setting (visible) this key is omitted |
    | invisible   | This point is marked as invisible                       | if the point was left on the default setting (visible) this key is omitted |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Cuboid">
    Cuboid labels are 3D labels and therefore contain the position, orientation, and dimensions of the cuboid.

    ```json theme={"dark"}
    "cuboid": {
      {
      "cuboid": {
        "position": [4.537997746722736, -4.036436904027065, 1.0422150246829245],
        "orientation": [7.400697375091305e-17, 2.0779014832905546e-16, 2.5017234942760873],
        "size": [2.9918133567776724, 2.386963438734146, 1.4666344382239702]
        }
      }
    }
    ```

    | Key         | Description                                                 | Notes                                                                                                                 |
    | ----------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
    | position    | The X,Y, Z coordinates of the cuboid’s center               | Expressed in the world coordinate system                                                                              |
    | orientation | Euler angles  (Roll, Pitch, Yaw) of the label's orientation | In units of radians                                                                                                   |
    | size        | Dimensions of the cuboid in its local coordinate frame.     | Length along the cuboid’s local X-axis, width along the cuboid's local Y-axis, height along the cuboid’s local Z-axis |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Segmentation">
    Segmentations are exported as rleStrings. See our [section on exporting Bitmasks & Segmentations](/platform-documentation/Annotate/annotate-export/annotate-export-json#export-bitmasks-%26-segmentations) to learn more.

    ```json theme={"dark"}
    {
      "segmentation": "bj41o000000000000O1000O11O00001O00O1001O000001O00000000000000000000000O10000000O10000000000000000000000000000000000O1000000001OO1000O100000O10000000000000000000000001OO1000O1OSO0l0200000O1000000000000000000000000O10",
      "shape": "segmentation"
    }
    ```
  </Accordion>
</AccordionGroup>

### Export Bitmasks & Segmentations

Bitmask labels are exported as `rleString`s. See our [SDK documentation](/sdk-documentation/sdk-labels/sdk-export#decode-bitmask-labels) to learn how to decode an `rleString`.

<Tip>We strongly recommend exporting [Bitmask labels using the Encord SDK](/sdk-documentation/sdk-labels/sdk-export#export-bitmasks). Bitmasks are exported in the JSON format.</Tip>

<Tip>Use the [COCO API](https://github.com/cocodataset/cocoapi) to [decode Bitmasks when using the COCO export format](/sdk-documentation/sdk-labels/sdk-export#decode-bitmask-labels).</Tip>

## Exporting Data Groups

When exporting Data Group labels, 1 JSON file the Data Group plus 1 JSON for each data unit in the Data Group are generated.

```json Data Groups Label Export theme={"dark"}
[
  {
    "label_hash": "c401d331-71f7-46c0-a279-40bc33ff4565",
    "branch_name": "main",
    "created_at": "2026-01-09 14:35:59",
    "last_edited_at": "2026-01-09 16:41:52",
    "dataset_hash": "6d1cfc37-afd3-481c-8984-55721c272ca9",
    "dataset_title": "Surgery Videos",
    "data_title": "Patient 1",
    "data_hash": "faa047cf-b980-408a-2fb7-01e59a55a3c4",
    "backing_item_uuid": "ab8450fa-ca17-4o24-9c4b-82c5441491ae",
    "data_type": "group",
    "is_image_sequence": null,
    "data_units": {
      "faa047cf-b980-408a-8fb7-01e59a35a3c4": {
        "data_hash": "faa047cf-b980-408a-8fb7-01e5gda35a3c4",
        "data_title": "Patient 1",
        "data_type": "application/vnd.encord.data.group",
        "data_sequence": 0,
        "labels": {},
        "metadata": {
          "children": [
            {
              "data_hash": "10a19807-7d3b-4be5-9hb0-ab23c22b06b",
              "name": "surgery_1",
              "label_hash": "0ea6dac2-7186-42ba-85f7-b94560f0f28b",
              "layout_key": "1"
            },
            {
              "data_hash": "20f42de1-d795-4e58-b70e-130af35c910",
              "name": "surgery_2",
              "label_hash": "97c007da-932c-4a8d-a221-9ec212d7d30",
              "layout_key": "2"
            },
            {
              "data_hash": "d0d19621-7d53-4b25-af54-454ae125caf7",
              "name": "surgery_3",
              "label_hash": "8c49a5ce-7bbc-4051-84fe-c21582218329",
              "layout_key": "3"
            }
          ]
        }
      }
    },
    "object_answers": {
      "4+ss5MKZ": {
        "objectHash": "4+ss5MKZ",
        "featureHash": "/tay334G",
        "classifications": [],
        "range": [],
        "createdAt": null,
        "createdBy": "bestdoctor@hostital.org",
        "lastEditedAt": "Tue, 07 Jan 2025 12:25:36 GMT",
        "lastEditedBy": "bestdoctor@hostital.org",
        "spaces": {
          "929bf651-8702-4c3d-ac1c-2debfb4d7991": {
            "type": "frame",
            "range": [
              [0, 2]
            ]
          }
        }
      }
    },
    "classification_answers": {
      "8f2a1b9c-4d5e-6f7a-8b9c-0d1e2f3a4b5c": {
        "classificationHash": "8f2a1b9c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        "classificationName": "Type of Surgery",
        "featureHash": "g9h8i7j6",
        "manualAnnotation": true,
        "answers": [
          {
            "featureHash": "k5l4m3n2",
            "name": "Heart",
            "value": "heart"
          }
        ]
      }
    },
    "object_actions": {},
    "label_status": "LABEL_IN_PROGRESS",
    "is_valid": true,
    "spaces": {
      "b2bcfcbd-b2df-4690-aa17-3d4a8f055a74": {
        "labels": {},
        "space_type": "video",
        "child_info": {
          "layout_key": "1",
          "file_name": "surgery_1"
        },
        "number_of_frames": 2182,
        "width": 1280,
        "height": 720
      },
      "929bf651-8702-4c3d-ac1c-2debfb4d7991": {
        "labels": {
          "0": {
            "objects": [
              {
                "objectHash": "4+ss5MKZ",
                "featureHash": "/tay334G",
                "name": "New object",
                "color": "#D33115",
                "value": "new_object",
                "createdAt": "Fri, 09 Jan 2026 14:35:59 UTC",
                "confidence": 1,
                "lastEditedAt": "Fri, 09 Jan 2026 14:35:59 UTC",
                "shape": "bounding_box",
                "createdBy": "bestdoctor@hostital.org",
                "lastEditedBy": "bestdoctor@hostital.org",
                "manualAnnotation": true,
                "boundingBox": {
                  "h": 0.2,
                  "w": 0.3,
                  "x": 0.6,
                  "y": 0.4
                }
              }
            ],
            "classifications": []
          }
        },
        "space_type": "video",
        "child_info": {
          "layout_key": "2",
          "file_name": "surgery_2"
        },
        "number_of_frames": 3239,
        "width": 1280,
        "height": 720
      },
      "ff9b7c98-67c0-4c16-a4cb-0ae3b7ab42ab": {
        "labels": {},
        "space_type": "video",
        "child_info": {
          "layout_key": "3",
          "file_name": "surgery_3"
        },
        "number_of_frames": 1558,
        "width": 640,
        "height": 360
      }
    }
  }
]
```

| **Key**                 | **Description**                                                                                                                                    | **Notes**                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| label\_hash             | The Label Row hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| branch\_name            | The branch the label belongs to                                                                                                                    | `main` is the default branch in non-Consensus Projects                                                                                   |
| created\_at             | Time and date the label was created                                                                                                                |                                                                                                                                          |
| last\_edited\_at        | Time and date the label was last edited                                                                                                            |                                                                                                                                          |
| dataset\_hash           | The Dataset's hash                                                                                                                                 | The 'hash' represents a unique identifier                                                                                                |
| dataset\_title          | The name of the Dataset                                                                                                                            |                                                                                                                                          |
| data\_title             | The Data Group's name                                                                                                                              |                                                                                                                                          |
| data\_type              | The data unit's file format                                                                                                                        | Always `group` for Data Groups                                                                                                           |
| is\_image\_sequence     | "true" when the data unit is an image sequence                                                                                                     | Always "null" for Data Groups                                                                                                            |
| data\_units             | List of all files the Data Group is composed of                                                                                                    | Details of the export information for `data_units` can be found below                                                                    |
| data\_hash              | The Data Group hash.                                                                                                                               | The 'hash' represents a unique identifier for the Data Group                                                                             |
| data\_title             | The Data Group's name                                                                                                                              |                                                                                                                                          |
| data\_type              | The data unit's file format                                                                                                                        | Always `group` for Data Groups                                                                                                           |
| data\_sequence          | The sequence number of this file within the data unit.                                                                                             | 0 represents the first file                                                                                                              |
| labels                  | A list of all frames contained in the Data Group                                                                                                   | This value is always 0                                                                                                                   |
| metadata                | Lists the metadata on the Data Group                                                                                                               |                                                                                                                                          |
| children                | lists the data units contained in the Data Group                                                                                                   | `layout_key` specifies where in the Data Group the data units appears in the Label Editor                                                |
| object\_answers         | All the attributes in this data unit                                                                                                               | The object attributes are identified using their hash                                                                                    |
| classification\_answers | All the classifications in a particular data unit                                                                                                  | The classification labels are identified using their hash                                                                                |
| object\_actions         | The number of states a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) can be in. | A change in state occurs each time the attribute answer changes. The objectHash within the object\_actions is the attribute answer's ID. |
| label\_status           | Indicates whether the data unit has been labeled                                                                                                   |                                                                                                                                          |
| is\_valid               | Indicates whether the Data Group is valid                                                                                                          |                                                                                                                                          |
| spaces                  | Root-level map of labeling spaces                                                                                                                  | Maps individual data spaces to metadata describing their structure and characteristics.                                                  |
| labels                  | Frame-level annotations                                                                                                                            | Keyed by frame number (as a string). Contains objects and classifications specific to that frame                                         |
| space\_type             | The type of media in this space                                                                                                                    |                                                                                                                                          |
| child\_info             | Metadata linking the space to a child unit                                                                                                         |                                                                                                                                          |
| number\_of\_frames      | Total frames available in this space                                                                                                               |                                                                                                                                          |
| width                   | The pixel width of the media                                                                                                                       |                                                                                                                                          |
| height                  | The pixel height of the media                                                                                                                      |                                                                                                                                          |
| layout\_key             | The unique identifier used to position the file within the Label Editor layout                                                                     |                                                                                                                                          |
| file\_name              | The name of the specific file associated with this space.                                                                                          |                                                                                                                                          |
| type                    | The unit of measurement for the range                                                                                                              | For example `frame`                                                                                                                      |
| range                   | The range the object or classification occurs on                                                                                                   |                                                                                                                                          |

### Multi-Layer Data Groups

Multi-layer Data Groups contain a `root` key that contains properties pertaining to the Data Group as a whole.

## Exporting Labels using the SDK

Go [here](/sdk-documentation/sdk-labels/sdk-export) to learn how to export labels using SDK.

## Label Branches

The branch associated with the labels is specified using the `branch_name` key.

The main branch is always displayed first and is identified by the following value:

```json theme={"dark"}
"branch_name": "main"
```


# How To Export Labels
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels



## Export Labels to Cloud Storage (Recommended)

Connect an [**Export** stage](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#export) to your Workflow to automatically sync labels to your cloud storage as tasks move through it. Every task that passes through the Export stage is synced to your chosen storage destination. Once the sync completes, tasks automatically continue to the next stage in your Workflow.

<Note>
  When the same task passes through the export node more than once, its labels are overwritten each time.
</Note>

This allows you to build a fully automated labeling pipeline, from task creation through to label delivery, without any manual exports.

### Prerequisites

1. Automatically exporting labels to cloud storage requires at least one cloud integration to be set up. Learn how to set up cloud integrations [here](/platform-documentation/General/annotate-data-integrations).

2. Your cloud storage integration must have **write permissions** enabled for the export to work. If you have an existing integration, ensure the integration you plan to use for export has write permissions before connecting it to the Export stage.

### Setup

**When editing, or creating a Workflow**:

1. Add and connect an **Export** stage to your Workflow.
2. Click the **Export** stage to open its configuration panel.
3. Select the cloud storage integration you want to export to from the dropdown menu.

<div>
  <img />
</div>

4. Add a path to export to within your cloud storage. This is the folder path where labels are exported to.
5. Select an export **Format**. The default is **Encord JSON**. Select **YOLO** to export labels in YOLO format directly to cloud storage.

### YOLO Format Export

<Note>
  YOLO format export using the cloud label-export workflow node requires the feature to be enabled on your account. Contact your Encord account team if this option is not visible in your workflow editor.
</Note>

When you select **YOLO** as the export format, an additional **Class mapping** selector appears. This selector lists the ontology external-ID namespaces configured on your Project's Ontology. Encord uses the selected namespace to map Ontology features to YOLO class numbers at export time.

<Note>
  YOLO class numbers are resolved live from the Ontology's external IDs each time a task is exported. YOLO class numbers are not snapshotted when you save the workflow node. If you update your Ontology's external IDs after configuring the node, the next export uses the updated mappings.
</Note>

<Warning>
  You must select a **Class mapping** namespace before you can save the workflow. If YOLO format is selected but no class mapping is chosen, Encord displays the validation error: *"YOLO export requires a class mapping to be selected."*
</Warning>

If no namespaces are configured on your Ontology, the **Class mapping** selector is disabled. You must configure YOLO class IDs on the Ontology before you can use YOLO export. Click **Configure Ontology Mapping** in the node settings panel to open the Ontology's external IDs settings page and set up your class mappings.

After you select a namespace, the panel displays a preview of up to five Ontology feature-to-class-number mappings for the selected namespace.

## Export Labels Manually

<Warning>
  If using Windows, we recommend using [7-Zip](https://www.7-zip.org/) to unzip the exported labels.
</Warning>

<Info>Only Project admins can export labels</Info>

<Tip>Descriptions of all information contained in the export file can be found [in the export file reference](/platform-documentation/Annotate/annotate-export/annotate-export-json).</Tip>

<iframe title="YouTube video player" />

<Tip>
  To export labels for specific tasks:

  1. Select the tasks
  2. Click **Bulk actions**
  3. Select **Export**
</Tip>

1. Click **Export** while in a Project.

   The *Export labels* dialog appears.

2. Specify the following:
   * **Format:** Specify the format to export the labels (JSON or COCO).
   * **Stage:** Specify the Workflow stage to export the labels from.
   * **Generate signed URLs:** Specify whether to generate signed URLs for the data units that have labels.
   <Note>
     Enabling this option can significantly increase export times.
   </Note>
   * **Save as new version:** Specify to version the labels.
     * Provide a meaningful name for the label version.
   * **Labels to include:** Specify the labels to include. You can export all labels or select specific object or classification labels to export.

3. Click **Export**.

   A *Labels export in progress* toast message appears.

### Data Group Label Format Options

When exporting labels, you can choose between two data group label formats:

* **New**: The recommended format that organizes data group labels in the parent row for improved structure and performance.
* **Legacy**: The previous format that places data group labels in children rows. This option is available for backward compatibility.

<Note>
  The **New** format is selected by default and is recommended for all new exports. The **Legacy** format will be removed in a future update.
</Note>

The Data Group label format option appears in the export configuration dialog alongside other export settings like format type and workflow stage selection.

## Export Labels for Multi-sensor Scenes

When you combine multiple LiDAR sensors into a single Scene, each sensor uploaded as its own point cloud file, pre-processed and transformed into a shared coordinate frame so they overlay in the editor—Encord treats the Scene as one data unit. On export you receive one label file (one Label Row, identified by a single label\_hash), not one file per sensor.

Within that single label file, each input point cloud file is represented as its own Space. Every file's labels are attributed to it individually using its stream\_id, uri, and event\_index, so you can always tell which sensor a label belongs to. You get "one label per input file", meaning per-file attribution nested inside one exported Scene and not separate files.

How labels map to sensors depends on the label type:

Segmentation labels reference point indices within a specific point cloud file, so they are inherently per-file.
Cuboids, polylines, and keypoints are 3D shapes defined in the Scene's shared coordinate frame. A single cuboid drawn over the combined cloud is one 3D object in scene coordinates—it is not duplicated per sensor.

<Note>
  This applies only when the sensors are registered together as a Scene. If the point clouds are instead uploaded as separate standalone items, each becomes its own Label Row and exports as a separate label file—but they do not overlay in a single editor view.
</Note>


# How to Label Audio
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-audio



<Warning>
  You can only use *Audio Region* objects, and classifications to label audio files. See our [end-to-end guide on labeling audio files](/end-to-end/Modalities/audio) to learn how to set up audio specific Ontologies.
</Warning>

## Label Audio Files

Navigate to the *Queue* tab of your Project and select the data unit you want to label.

**To label an audio region**:

1. Select a *Audio Region* class from the left side menu.

2. Click and drag your cursor along the waveform to apply the label between the desired start and end points. Repeat this as many times as necessary while the class is selected.

3. If required, apply any attributes to the region.

4. Repeat these steps for as many regions as necessary.

<Tip>
  Audio regions can be copy-pasted using <kbd>CMD</kbd> / <kbd>CTRL</kbd>  + <kbd>C</kbd> and <kbd>CMD</kbd>  <kbd>CTRL</kbd> + <kbd>V</kbd>.
</Tip>

<Tip>When assigning multiple *Audio Region* class labels to the same section of an audio file, hide overlapping labels.</Tip>

<div>
  <img />
</div>

**To apply the classification to the entire audio file**:

<iframe title="YouTube video player" />

1. Select the Classification from the left side menu.

2. For radio buttons and checklists, select the value(s) you want to classification to have. For text classifications, enter the desired text.

### Fill Range to the Playhead

You can quickly snap the boundary of a selected audio classification or audio region range to the current playhead (the visual marker on the timeline or waveform) position using the **Fill to playhead** action. This is useful when you want to extend a range to an exact point without manually dragging the timeline handle.

<Tip>
  Position the playhead at the desired boundary point, select the audio classification/audio region range, then press `Alt+V` (Windows/Linux) or `Option+V` (Mac) to extend the nearest range edge to the playhead. You can also click **Fill to playhead** in the **Available Actions** panel in the left sidebar.
</Tip>

The action automatically determines which edge to move:

* If the playhead is **past the end** of the range, the end boundary extends to the playhead.
* If the playhead is **before the start** of the range, the start boundary extends to the playhead.
* If the playhead is **inside** the range, the action does nothing — it only ever extends a range outward, never trims it.

<Note>
  **Fill to playhead** is only available for editable ranges. The action and hotkey have no effect on read-only or locked ranges.
</Note>

<Tip>
  Use **Fill to playhead** together with the other range-editing shortcuts for fast, keyboard-driven timeline work:

  | Action                          | Windows/Linux     | Mac                  |
  | ------------------------------- | ----------------- | -------------------- |
  | Fill selected range to playhead | `Alt+V`           | `Option+V`           |
  | Expand range right              | `Alt+Right`       | `Option+Right`       |
  | Shrink range right              | `Alt+Left`        | `Option+Left`        |
  | Expand range left               | `Alt+Shift+Left`  | `Option+Shift+Left`  |
  | Shrink range left               | `Alt+Shift+Right` | `Option+Shift+Right` |
</Tip>

### Editing Exact Classification Frame Ranges

When you select a classification in the left sidebar while the Label Editor is in edit mode, the frame range bounds display as editable **Range start** and **Range end** input fields instead of static text chips. This lets you type an exact frame number or timestamp to adjust a classification's range boundary directly, without needing to drag the timeline.

<Note>Editable range inputs are only available when the Label Editor is in edit mode, the classification is selected, and the label is not read-only. When these conditions are not met, the range bounds display as static text chips as before.</Note>

### Propagating Dynamic Attributes Across Disjointed Object Ranges

When an object appears only on disjointed (non-contiguous) frame ranges — for example, every few frames — setting a dynamic attribute normally writes only to the end of the sub-range containing the playhead. The **Propagate across gaps** setting changes this behavior so that the attribute value automatically covers all later sub-ranges of the same object.

To enable this setting, open **Timeline settings** and locate the **Dynamic attributes** section, then turn on **Propagate across gaps**. The setting is off by default.

When **Propagate across gaps** is on:

* Setting a dynamic attribute at the playhead propagates the value forward through all later sub-ranges of the object, stopping only at the next deliberately-set keyframe for that attribute.
* Editing or clearing a propagated value at any frame applies the change forward through all later sub-ranges from that point, while any deliberately-set later keyframe remains unchanged.
* For checklist attributes, each option propagates independently. Only a keyframe for the same checklist option stops propagation of that option — keyframes for other options do not affect it.

<Note>When **Limit to a single frame** is also enabled, it takes precedence and **Propagate across gaps** has no effect.</Note>

### Copy-Paste Labels

You can copy and paste Audio Region labels.

1. Select the range(s) from the timeline.
2. Press <kbd>Ctrl</kbd> + <kbd>C</kbd> (Windows) or <kbd>Cmd</kbd> + <kbd>C</kbd> (Mac) to copy.
3. Click the part of the timeline you want to paste to.
4. Press <kbd>Ctrl</kbd> + <kbd>V</kbd> (Windows) or <kbd>Cmd</kbd> + <kbd>V</kbd> (Mac) to paste.

### Bulk Class Changes for Audio Regions

You can change the class of multiple audio regions at once using the timeline selection feature.

<Note>
  This feature is only available for Audio Region objects in the timeline view.
</Note>

**To change the class of multiple audio regions**:

1. In the audio timeline, select multiple regions by clicking and dragging across the desired regions while holding `Ctrl` (Windows) or `Cmd` (Mac).

2. Right-click on any of the selected regions to open the context menu.

3. Select **Change class** from the menu.

4. In the **Change class** modal, choose the target class you want to apply to all selected regions.

5. Click the target class to confirm the change.

<Tip>
  The modal header displays "Change class of X selected" where X is the number of selected ranges.
</Tip>

All selected regions are converted to the new class while preserving their time boundaries and any existing attributes.

## Audio Transcription

<Warning>To create audio transcriptions, your Ontology must include *Audio Region* objects with [*Transcript* attributes](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#transcript-attributes).</Warning>

<div>
  <iframe />
</div>

Navigate to the *Queue* tab of your Project and select the data unit you want to label.

<Note>
  The process outlined here assumes the Admin has configured an Ontology that includes *Speaker* and *Transcription* in the same Audio region.

  ![Audio region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/transcription-settings-01.png)
</Note>

**To transcribe an audio region**:

1. Select an *Audio Region* class from the left side menu.

2. Perform one of the following:

   * **Use Timeline (Recommended):** Click and drag your cursor along the *Timeline* under the audio file to apply the label between the desired start and end points.

   <Note>
     When using the *Timeline*, click and drag your cursor at the root for the text region to create new instances of text regions. For example for multiple *Speakers*.
   </Note>

   * **Use Waveform:** Click and drag your cursor along the waveform to apply the label between the desired start and end points.

3. Fill in the content for the *Speaker* and for *Transcription* to the labeled audio region as text.

4. Repeat these steps for as many regions as necessary.

<Tip>
  * When assigning multiple *Audio Region* class labels to the same section of an audio file, hide overlapping labels.

  * Select multiple regions using `SHIFT +`.

  * Bulk merge regions by selecting multiple audio regions from the same class, right-click, and click **Merge ranges into** and select the class to merge.
</Tip>

### Transcription Pane

The Audio Transcription Pane is available when your Ontology includes at least one *Transcription* attribute. To access it, click the icon at the top of the Label Editor. The Transcription Pane opens on the right side, displaying all transcriptions in chronological order.

<div>
  <img />
</div>

## Long Audio Files

When audio files in your cloud storage are longer than an hour, the Label Editor may take extra time to load their waveforms. To significantly reduce load times, you can generate a JSON file containing the waveform data and store it alongside your audio file.

<Tip>
  We STRONGLY recommend generating a waveform file for any audio files that are an hour or longer in duration.
</Tip>

1. Install [audiowaveform](https://github.com/bbc/audiowaveform).

2. Use the following command to generate a JSON file of your waveform:

<Note>
  The name of the JSON file must exactly match the name of your audio file. Only the file extensions differ.
</Note>

<CodeGroup>
  ```bash command theme={"dark"}
  audiowaveform -i ./input.mp3 -o ./waveform-output.json
  ```

  ```bash example theme={"dark"}
  audiowaveform -i "/Users/chris/Documents/awesome-audio-file-01.mp3" \
    -o "/Users/chris/Documents/awesome-audio-file-01.json"
  ```
</CodeGroup>

3. Upload the JSON file to the location of your audio file.

<Note>
  The JSON file MUST reside in the same cloud storage location as your audio file.

  For example:

  * Audio File Path in Bucket : "/my-bucket/all-audio/my-favorite-song.mp3"
  * Audio Waveform File Path in Bucket: "/my-bucket/all-audio/my-favorite-song.json"
</Note>

<Tip>
  You can upload the JSON file during audio file import or any time after.
</Tip>


# DICOM and NifTi
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-dicom



Encord provides native support for Digital Imaging and Communications in Medicine (DICOM) browser rendering and data annotations. The editor also supports NIfTI (Neuroimaging Informatics Technology Initiative). With the DICOM editor, you can:

* Annotate modalities such as CT, X-ray, and MRI.
* Label using any annotation type for the Primary view and bitmasks in non-Primary views in 2 and 3 dimensions, and seamlessly toggle between axial, coronal, and sagittal views.
* Render 20,000 pixel intensities and set custom window widths and levels.
* Natively display DICOM metadata.
* Track and interpolate objects between slices.
* Reduce manual annotations with automation features.

<Note>"Slices" and "Frames" are used interchangeably in our DICOM editor documentation.</Note>

The following video provides a summary of DICOM Label Editor capabilities.

<div>
  <iframe />
</div>

<Warning>**We recommend using the Firefox browser when working with DICOM or NIfTI files**, as it does not have a tab memory limit. Tab memory limits in other browsers such as Chrome may cause issues when loading large DICOM or NIfTI files.</Warning>

<img />

DICOM editor components:

* **A**. Load previous/next DICOM file.
* **B**. Toolbar with scissors (bulk vertex removal), measurement tools, windowing adjustment, image centering, and zoom.
* **C**. Editor menu.
* **D**. Slice slider and sliceskip interval.
* **E**. Instances and frame labels.
* **F**. Classes.

<Note>The following sections describe general functionality for all DICOM modalities. If you are looking for Mammography specific features on the Encord platform please have a look [here](/platform-documentation/Annotate/annotate-label-editor/annotate-mammo)</Note>

If you have questions regarding a specific modality or datatype, please reach out to us at [support@encord.com](mailto:support@encord.com).

## Task Management

Before getting into the details of the label editor and making annotations, note the following about scheduling annotation work. Annotation is done in the annotation phase of the task management system. To ensure annotation work is saved properly, each labeling task must be properly assigned to an annotator, annotators must always access the task through the **Queue** tab in the Task Management System, and only the assigned annotator works on any given task at any given time.

***

## Navigation

### Move between slices

There are a number of different ways to skip through slices in a DICOM file:

* Using <kbd>Left</kbd> and <kbd>Right</kbd> arrow keys on your keyboard.
* Using the forward and backward buttons on the editor.
* By scrolling using your mousewheel or trackpad.
* By scrubbing through, or clicking anywhere on the progress bar.

<div>
  <img />
</div>

The number of slices skipped is determined by the specified *Frameskip interval*. *Frameskip intervals* can be set using the predefined values, or customized by entering a value in the *New* input and clicking the *Plus* icon.

<div>
  <img />
</div>

***

### Zoom and Pan

* Hold the <kbd>Shift</kbd> key and drag to pan, and move a DICOM slice around on the page.
* To zoom in or out of a slice:
  * Hold <kbd>Shift</kbd> and use the <kbd>Up</kbd> and <kbd>Down</kbd>  keys to zoom into the center of the slice.
  * Hold <kbd>Shift</kbd>  while scrolling using your laptop's trackpad to zoom into a particular point.

<div>
  <img />
</div>

<Tip>You can zoom and pan on every slice / view in a series.</Tip>

***

### Progressive Loading

You don't have to wait for your file to finish loading before navigating to your desired frame! Simply drag the cursor to, or click the progress bar on, the location of the frame you would like to view while it is still loading, and the file will continue loading from the desired location, as seen in the following video. The light-blue color on the progress bar indicates how much of your file has been loaded.

<div>
  <img />
</div>

***

### Crosshair Navigation

Crosshair mode can be activated using the *Crosshair* icon in the floating bar.

Left-clicking in a view updates the other views automatically so that the displayed image planes match the selected location.

<div>
  <img />
</div>

***

### Deeplinking - Copy and share URLs

Seamlessly copy the URL of the slice currently being viewed by clicking the *Share* icon, shown below.

<div>
  <img />
</div>

Share the URL to guide users to a specific slice or frame.

***

## Display

NifTi uses AXIAL orientation for the primary view.

DICOM uses DICOM uses the data from the header (slice orientation and slice position tags) for the orientation for the primary view.

### Intensity values

The Encord DICOM viewer renders DICOM files natively in the browser, enabling the display of the full range of the intensity values (i.e., 20,000+ pixel intensities).

<Note>Intensity values take the form of [Hounsfield units](https://en.wikipedia.org/wiki/Hounsfield_scale) for CT scans.</Note>

Intensity values are projected directly on the image. The example below has the cursor pointing to Hounsfield Value 1591 o.

<div>
  <img />
</div>

***

### Window Width (WW) and Window Level (WL)

Toggle the DICOM windowing settings menu by clicking the *sliders* icon in the viewer pane. Adjust window width and level using the sliders or setting your required input values. Save custom levels as presets for quick access later.

<div>
  <img />
</div>

Use the windowing adjustment functionality by clicking the *Adjust windowing* button in the toolbar or pressing <kbd>alt</kbd> + <kbd>w</kbd> on your keyboard. Next, press the left mouse button and drag the mouse to change the window width or level:

* **Up**: Increase window level.
* **Down**: Decrease window level.
* **Left**: Shrink window width.
* **Right**: Expand window width.

<div>
  <img />
</div>

***

### VOI LUT Transfer Function

The **VOI (Value Of Interest) LUT (Look-Up Table) Function**, specified in the DICOM metadata Tag [(0028,1056)](https://dicom.innolitics.com/ciods/ct-image/voi-lut/00281056), defines how pixel values are mapped from **Modality LUT output** to **Presentation LUT input**, affecting image contrast and brightness.

The Encord DICOM viewer supports **Linear** and **Sigmoid** VOI LUT transfer functions.

<Info>
  For a detailed explanation of VOI LUT Transfer Functions, refer to the official DICOM documentation [here](https://dicom.nema.org/medical/dicom/current/output/chtml/part17/chapter_Y.html).
</Info>

* By default, the VOI LUT Transfer Function is set to the value provided in the DICOM metadata. If no value is provided the Linear VOI LUT Transfer Function is used.
* You can **manually switch between Linear and Sigmoid transfer functions** using the toggle.
* This function controls how grayscale values are adjusted for optimal image display, ensuring better visibility of structures in medical imaging.

<div>
  <img />
</div>

***

### Multiplanar Reconstruction (MPR)

Encord's MPR display reconstructs 2D orthogonal images (coronal, sagittal, axial) for enhanced visualization, analysis, and annotation of anatomy. Annotations made in the one view automatically appear in all other views, and cross-reference lines are projected across all three views, assisting with precise anatomy annotation.

MPR views are toggled on or off in the [DICOM editor settings](#dicom-editor-settings).

<Tip>All reconstructed views can be [rendered in 3D](#3d-volume-rendering).</Tip>

By default, the primary view is shown in the main annotation window on the left of the Label Editor, and reconstructed images are shown in smaller windows on the right. Use the MPR dropdown to switch between different views in any window - the primary view is always clearly labeled with the word **PRIMARY**.

<div>
  <img />
</div>

**Labeling reconstructed views**

<Note>Only [Bitmask](#segmentation-masks--bitmasks) labels can be applied to reconstructed views. </Note>

Labels can be applied to primary and reconstructed views. When a label is created it automatically shows up in all other views. You can change the tile currently being annotated using the [*Annotate from this tile* button](#switch-annotation-series), however we recommend creating labels in the main annotation window.

<div>
  <img />
</div>

**How to disable MPR**

MPR views are automatically displayed when a 3D volume is detected. To turn this off, disable the *Default to MPR layout*  toggle in the *DICOM settings* section of the [Editor settings](#dicom-editor-settings).

<div>
  <img />
</div>

***

### 3D Volume Rendering

Medical scans can be explored in 3 dimensions, allowing for a more intuitive assessment of anatomical structures.

<Note>3D volume rendering is only available for volumes - which Encord determines through `.dcm` file tags.</Note>

<div>
  <img />
</div>

To enable 3D volume rendering:

1. Open the Additional controls pane by clicking the *Additional controls* icon.
2. Enable the *Full 3D* toggle.
3. (Optional) The 3D volume can be rotated by clicking and moving the mouse while holding down the <kbd>Alt</kbd> key on Windows, or the  <kbd>Option</kbd> key on Mac.

***

### Switching Series in the Label Editor

Use the drop-down menu in the viewport to seamlessly switch between any series in the Project.

<div>
  <img />
</div>

* **1** - Patient ID
* **2** - [Study ID](https://www.google.com/url?q=https://dicom.innolitics.com/ciods/rt-plan/general-study/0020000d\&sa=D\&source=docs\&ust=1705516719484780\&usg=AOvVaw10I1qZ4k1Z8xnmPfmLf8MF)
* **3** - Series title

Click a Series title to open the series in the Label Editor.

<Tip>If the *Study level Classifications* toggle in the Project's Settings is Enabled you can click the Study ID to apply Classifications to the entire study.</Tip>

### Multiple Series Viewing

In the drop-down menu of the viewport you can add other series to be viewed at the same time. Annotations will be seen on all the series being viewed, as seen in the screenshot below.

<div>
  <img />
</div>

Only series that are part of the same [Dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets) are available for selection. If you want to view multiple series in one session, ensure they are part of the same Dataset.

<div>
  <img />
</div>

<Note>We are currently working on a feature that will allow for synchronous scrolling of multiple series.</Note>

***

### Maximum intensity projection (MIP)

Clicking the *sliders* icon in the corresponding viewer pane and then changing the slab thickness (ST) to something greater than 0 enables MIP mode. MIP can be switched on/off for each individual view. Note that annotations are not shown in MIP mode. To disable MIP mode change the ST back to 0.

<div>
  <img />
</div>

***

### Hanging protocols

Hanging protocols allow you to select how many entities within a study are displayed at the same time. This allows you to, for example, view the same CT scan slice at different moments in time.

<div>
  <img />
</div>

#### Presets

You can save presets for a given layout by typing a meaningful name after making a protocol selection, and clicking the **+** button. Click the tick icon next to a preset name to select the preset as your default layout.

#### Default layouts

You can specify any preset, including [*Auto layout*](#auto-layouts), as the default layout for studies in the Label Editor.

Click the tick icon next to a preset in the [hanging protocols menu](#hanging-protocols), to select the preset as your default layout.

You can reset the Label Editor to the default layout by clicking the *Reset layout to default* icon.

<div>
  <img />
</div>

#### Auto layouts

Auto layouts are common layouts for viewing DICOM studies in the Label Editor. Auto layouts are set in the [DICOM editor settings](#dicom-editor-settings). This includes the *MPR layout* setting and the *Mammography layout* setting for mammography files.

Selecting the **Auto layout** option resets the Label Editor to your auto layout. You can specify the  **Auto layout** option as your [default layout](#default-layouts).

<div>
  <img />
</div>

***

### Metadata

<Note>Metadata is not supported for NIfTI.</Note>

<Note>Ensure your DICOM files and [metadata](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#metadata) follow the format outlined in the [official DICOM specification](https://dicom.nema.org/medical/dicom/current/output/chtml/part05/sect_6.2.html).</Note>

The Encord DICOM metadata viewer renders DICOM files natively in the browser, allowing you to access all defined metadata fields and sequences associated with the DICOM file.

The metadata viewer is displayed by toggling the *View metadata* button above the series being annotated. The metadata viewer contains a search bar allowing you to search for specific types of metadata.

<div>
  <img />
</div>

<Note>A note appears warning the user if 'Pixel spacing' is missing from an entity's metadata. Pixel spacing is essential for [making accurate distance measurements](#distance-measurement).</Note>

The metadata is organized into the following columns for easy interpretation:

* **Field Name**: This column displays the name of the metadata field.
* **Tag**: Represented in the format (group, element), the Tag column consists of two hexadecimal values enclosed in brackets. These values uniquely identify the metadata field.
* **Content**: This column shows the data or value associated with the field.

Metadata sequences provide additional layers of information and can be identified by the presence of the **+** icon. Clicking the **+** icon expands the sequence, revealing nested fields and changing to a **-** icon. Clicking the **-** icon collapses the sequence.

<div>
  <img />
</div>

#### Understanding the Tag column

The Tag column plays a vital role in identifying the type of metadata field:

* **Private fields**: If the fourth character of the group value in the Tag is an odd number - for example (0013,1001) - the field is considered private. Private fields may or may not display accurate Field Name and Content. In many cases, these fields have the Field Name listed as 'Unknown' and may contain empty or nonsensical content.

<div>
  <img />
</div>

* **Standard fields**: If the fourth character of the group value is an even number and the Content field is empty - for example (0010,2000) - the field is genuinely empty and not a result of data being hidden.

<div>
  <img />
</div>

#### Data overlay toggle

The *Data overlay* toggle, located in the *Additional controls*, allows you to display or hide metadata overlay. When toggled on, metadata displays in the bottom left corner of the series being annotated.

<div>
  <img />
</div>

<Note>Custom DICOM metadata such as text reports from radiological descriptions can be rendered in popout drawers. To add drawers with custom DICOM metadata, contact [support@encord.com](mailto:support@encord.com) with the information you wish to represent.</Note>

#### Custom overlay

Create a custom overlay to display specific [metadata](#metadata) in the Label Editor by default.

<div>
  <img />
</div>

To set a custom overlay:

1. Navigate to the *Settings* tab of your Project.
2. Click **Upload** in the *DICOM* section.

<div>
  <img />
</div>

3. Upload a JSON file specifying the custom overlay you want to display in the Label Editor.
4. Click the **Preview** button to see what the custom overlay looks like.

<div>
  <img />
</div>

**Specifying custom overlays**:

A JSON file is used to define which elements are displayed as overlays in the Label Editor. The following JSON schema includes all possible overlay elements you can configure.

<Tip>Examples of overlay JSON files can be found [here](https://github.com/encord-team/dicom/tree/main/overlay/examples).</Tip>

```json theme={"dark"}
{
  "title": "DicomOverlayModel",
  "type": "object",
  "properties": {
    "items": { "$ref": "#/definitions/OverlayItems" },
    "fontSize": {
      "title": "Fontsize",
      "description": "The font size relative to Encord's default size. Default value is 1",
      "exclusiveMinimum": 0.5,
      "exclusiveMaximum": 3,
      "type": "number"
    }
  },
  "required": ["items"],
  "definitions": {
    "OverlayItem": {
      "title": "OverlayItem",
      "type": "object",
      "properties": {
        "content": {
          "title": "Content",
          "description": "A template string used to format a .dcm tag value, for example 'Modality: {00080060}', or information about the context, e.g. {sliceNumber}.\n- {sliceNumber}: the current slice number out of the total number of slices, starting from 0. Empty if there is only one slice. Example: '3/200'.\n- {pixelValue}: the pixel value at the current mouse position. Only for grayscale images.\n- {windowing}: the current windowing width and length. Example: 'W: 400 L: 40'",
          "maxLength": 100,
          "pattern": ".*\\{([0-9a-f]{8}|(sliceNumber)|(pixelValue)|(windowing))\\}.*",
          "type": "string"
        }
      },
      "required": ["content"],
      "additionalProperties": false
    },
    "OverlayItems": {
      "title": "OverlayItems",
      "type": "object",
      "properties": {
        "bottomLeft": {
          "title": "Bottomleft",
          "maxItems": 10,
          "type": "array",
          "items": { "$ref": "#/definitions/OverlayItem" }
        },
        "bottomRight": {
          "title": "Bottomright",
          "maxItems": 10,
          "type": "array",
          "items": { "$ref": "#/definitions/OverlayItem" }
        },
        "topLeft": {
          "title": "Topleft",
          "maxItems": 10,
          "type": "array",
          "items": { "$ref": "#/definitions/OverlayItem" }
        },
        "topRight": {
          "title": "Topright",
          "maxItems": 10,
          "type": "array",
          "items": { "$ref": "#/definitions/OverlayItem" }
        }
      },
      "additionalProperties": false
    }
  }
}

```

***

## Switch annotation series

You can seamlessly switch the series you'd like to annotate.

**To select a tile for annotation**

* Click the *Switch tiles* icon highlighted in the image below.
* Click the three dots icon highlighted in the image below and select **Annotate from this tile**.

**To move a tile to the one currently being annotated**

1. Click the three dots icon highlighted in the image below
2. Select **Annotate and swap tiles**.

<div>
  <img />
</div>

***

### Editor switch

The 'Editor switch' button ( <img /> ) enables you to select any series being displayed to be annotated without having to return to the task management system.

<div>
  <img />
</div>

***

### View full study

The Label Editor displays how many series are in part of the study currently being viewed. The **View full study** button allows you to view all series belonging to a study side-by-side.

<div>
  <img />
</div>

You can toggle the **View full study** button. When you toggle that button it turns into the **Hide full study** button.

<div>
  <img />
</div>

***

### Rotate the label editor

Click the *Rotate toolbar* icon at the top of the label editor to bring up a pop-up enabling you to rotate the label editor by using the slider, as shown below.

<div>
  <img />
</div>

<Tip>Click the *Rotate 90 degrees* icon to rotate the pop-up in increments of 90 degrees.</Tip>

***

## Tools

### Distance measurement

The distance measurement tool can be used to measure real-world distances between any two points on an image.  It uses the 'Pixel spacing' parameter - contained in an entity's [metadata](#metadata) - to accurately convert pixels into real-world distances that are displayed in millimeters.

<Note>For accurate measurements in mammography, the '[EstimatedRadiographicMagFactor](https://dicom.innolitics.com/ciods/digital-x-ray-image/dx-positioning/00181114)' needs to be contained within an entity's [metadata](#metadata). It is used as a scale factor to adjust the distance measurement and provide accurate results. The absence of the 'EstimatedRadiographicMagFactor' can result in errors when measuring distances in mammography. </Note>

The [Polyline Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#objects) displays the total length of the line in millimeters, rather than simply the distance between two points.

Enable the distance measurement functionality by clicking the <img /> button on the floating toolbar, or by pressing <kbd>alt</kbd> + <kbd>m</kbd> on your keyboard.

<div>
  <img />
</div>

To delete existing measurements the distance measurement functionality has to be enabled. Erase measurements by selecting a measurement and pressing <kbd>backspace</kbd> or <kbd>del</kbd> on your keyboard.

<div>
  <img />
</div>

***

### Distance export

Encord supports copying measured distances using the [polyline annotation type](#polyline), separate from using the [measurement tool](#distance-measurement) as detailed above.

1. Create a [polyline](#polyline) annotation.
2. Select the newly created [polyline](#polyline) and click the three dots on the *Quick toolbar* to copy the distance to your clipboard.

<div>
  <img />
</div>

***

### Measure angles

Polygon and polyline angles can be displayed in the label editor to provide useful insights into your labels.

1. Open the label editor *Settings* by clicking <img /> on the [editor header](/platform-documentation/Annotate/annotate-label-editor#editor-header).
2. Navigate to the *Drawing settings* section and enable the **Show polyshape angles** toggle. Click back on to the slice to display the angles.
3. Draw a polygon or polyline as you usually would.

<Note>Enabling the toggle will display angles for any existing polyshapes.</Note>

<div>
  <img />
</div>

***

## Annotation types

Objects are annotated using bounding boxes, polygons, polylines, keypoints or primitives. Slices are annotated using classifications. Instantiating objects or classifications in the DICOM editor generates a *UUID* that uniquely identifies that instance across a range of slices (i.e., in the spatial dimension).

The identifier is sometimes called a "track," with numerical IDs supplementing *UUIDs* for objects for visual aid.

Object instances can be assigned with static and dynamic attributes (i.e., spatial classifications that may change through the volume) as defined in the specified ontology. Static classifications define the global properties of an object (e.g., the surgical tool has three forks) whereas dynamic attributes change during the volume (e.g., the brain has a tumour present from slices 0 to 100 but none from frame 101 to 150).

Supported annotation types & corresponding features are listed in the table below. You can read more about the listed automation features <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#automation">here</a>.

| **Annotation type**    | **Dynamic attribute** | **Automated tracking** | **Interpolation** | **Import predictions** | **Model training & inference** |
| ---------------------- | --------------------- | ---------------------- | ----------------- | ---------------------- | ------------------------------ |
| Bounding box           | ✅                     | ✅                      | ✅                 | ✅                      | ✅                              |
| Rotatable bounding box | ✅                     | ✅                      | ✅                 | ✅                      | Coming soon                    |
| Polygon                | ✅                     | Coming soon            | ✅                 | ✅                      | ✅                              |
| Polyline               | ✅                     | ✅                      | ✅                 | ✅                      | Coming Soon                    |
| Keypoint               | ✅                     | ✅                      | ✅                 | ✅                      | ✅                              |
| Bitmask                | ✅                     | N/A                    | ✅                 | ✅                      | N/A                            |
| Object primitive       | N/A                   | ✅                      | N/A               | ✅                      | N/A                            |
| Frame classification   | N/A                   | N/A                    | N/A               | ✅                      | ✅                              |

***

### Bounding box

Creating a bounding box requires an Ontology with a bounding box annotation type. Instantiate a new bounding box instance by clicking on the specified class in the 'Classes' menu, or by using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Instantiating existing bounding box instances (i.e., bounding boxes that should keep the same identifier in preceding or succeeding slices) can be done by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>).

Bounding boxes can be copy/pasted between slices using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>c</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd>  + <kbd>v</kbd> to paste it on the desired slice. See this visual illustration.

<div>
  <img />
</div>

Bounding box instances can be assigned with static and [dynamic attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes) should they be defined in your Ontology.

* Highlight an object by clicking on it in the DICOM editor canvas or by clicking on the *Plus* icon or start/end slice in the range overview for the specified bounding box.

* Assign classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>).

#### Interpolation

Interpolation is run via the *Automated labeling* drawer. Click the *Automated labeling* button to open the drawer. Select *Interpolation* from the drop-down menu, select the desired objects to interpolate, set the interpolation range (i.e., the range of slices) and click the *Run interpolation* button. You need a minimum two labels of an instance to run interpolation.

Learn how to use interpolation for DICOM using the video tutorial below.

<AccordionGroup>
  <Accordion title=" Video Tutorial - Interpolation (DICOM) ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

You can read more about interpolation <a href="/platform-documentation/Annotate/automated-labeling/annotate-interpolation">here</a>.

***

### Polygon

Creating a polygon requires an Ontology with a polygon annotation type. Enable or disable free-hand drawing mode by pressing <kbd>d</kbd> on your keyboard. Polygon coarseness (for polygons drawn free-hand) is set in the *Drawing settings* section of the *Settings* (<img />).

Instantiate a new polygon instance by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

A polygon can be closed by double-clicking anywhere on the canvas. Doing so will "snap" creating an edge between the last vertex to the first vertex drawn.

You can create polygons using SAM 2, by placing vertices, or by using the polygon brush (<kbd>F</kbd>).

Instantiate existing polygon instances (i.e., polygons that should keep the same identifier in preceding or succeeding slices) by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>). See the <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#keypoint">keypoint documentation</a> for visual instructions on how to instantiate existing polygons.

Polygons can be copy/pasted between slices using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>c</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>v</kbd> to paste it on the desired slice.

Polygon instances can be assigned with static and [dynamic attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes) should they be defined in your Ontology:

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end slice in the range overview for the specified polygon.

* Assign classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>).

#### Interpolation

Run polygon interpolation following the instructions for bounding box, which you can find <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#interpolation">here</a>. Unlike other linear interpolation methods, Encord's polygon interpolation algorithm does not require a matching number of vertices between polygon objects in set keyframes. Our algorithm also allows you to draw polygons in arbitrary directions (e.g., clockwise, counterclockwise, and otherwise).

You can read more about interpolation <a href="/platform-documentation/Annotate/automated-labeling/annotate-interpolation">here</a>.

#### Editing polygons with the brush tool

You can edit existing polygons with the brush tool. This allows you to create complex shapes in a much faster way than going vertex by vertex. To use the brush tool, select an existing polygon and then click on the brush tool button. This will show the brush tool settings panel where you can choose the brush or eraser and change its size. Once you are done editing, click the "x" to go back to the label editor.

<div>
  <img />
</div>

***

### Polyline

Creating a polyline requires an Ontology with a polyline annotation type. Enable or disable free-hand drawing mode by pressing <kbd>d</kbd> on your keyboard. Polyline coarseness (for polylines drawn free-hand) is set in the *Drawing settings* section of the *Settings* (<img />).

Instantiate a new polyline instance by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

<div>
  <img />
</div>

Polylines can be copy/pasted between slices using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>c</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>v</kbd> to paste it on the desired slice.

Complete a polyline by double-clicking anywhere on the canvas.

Instantiate existing polyline instances (i.e., polylines that should keep the same identifier in preceding or succeeding slices) by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>).

Polyline instances can be assigned with static and [dynamic attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes) should they be defined in your Ontology:

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified polyline.

* Assign a classification by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>).

***

### Keypoint

Creating a keypoint requires an Ontology with a keypoint annotation type. Instantiate a new keypoint instance by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Instantiate existing keypoint instances (i.e., keypoints that should keep the same identifier in preceding or succeeding slices) by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>).

Keypoints can be copy/pasted between slices using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>c</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>v</kbd> to paste it on the desired slice.

<div>
  <img />
</div>

Keypoints instances can be assigned with static and [dynamic attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes) should they be defined in your Ontology:

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified keypoint
* Assign Classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>)

#### Interpolation

Run keypoint interpolation following the instructions for bounding box, which you can find <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#interpolation">here</a>.

***

### Object primitive

Creating a [primitive](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#object-primitives) (f.k.a. skeleton templates) requires an Ontology with a primitive annotation type. Use primitives to templatize shapes (example, 3D cuboids, pose estimation skeletons, rotated bounding boxes) commonly used by your annotation team.

<img />

*Create a primitive ontology for data labeling*

To instantiate a new primitive instance, click on the specified class in the 'Classes' menu or use the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Instantiate existing primitive instances (i.e., primitives that should keep the same identifier in preceding or succeeding slices) by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>).

Primitives can be copy/pasted between slices using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>c</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>v</kbd> to paste it on the desired slice.

Primitives allow you to define properties of edges defined in your template as visible, occluded, or invisible. Toggle the edge property settings for a primitive by highlighting the primitive and clicking the *Show controls* button.

Object primitive instances can be assigned with static and [dynamic attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes) should they be defined in your Ontology:

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified primitive.

* Assign classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>).

#### Interpolation

Run primitive interpolation following the instructions for bounding box, which you can find <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#interpolation">here</a>.

***

### Segmentation masks / Bitmasks

Bitmasks allow you to create labels using a brush tool to select parts of an image. This can be useful when creating labels for vessel outlines or labeling topologically separate regions belonging to the same [frame classification](/platform-documentation/General/annotate-glossary).

When creating a bitmask, the process continues until you press the <kbd>ENTER</kbd> or <kbd>ESC</kbd> key. This allows you to easily create complex bitmask labels without interruption.

<Note>Creating a bitmask segmentation requires an [Ontology with the *Bitmask* annotation type](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#objects).</Note>

<Tip>[Existing Bitmask labels can be updated](#updating-bitmask-labels) using the [brush tool](#brush-tool), [threshold brush](#threshold-brush), and [eraser](#eraser) tools.</Tip>

#### Brush tool

The brush tool is selected by clicking the brush icon or by pressing <kbd>f</kbd> on your keyboard while the popup is open.

<div>
  <img />
</div>

When using the brush tool, the 2D brush tool is selected by default. The 2D brush tool on creates bitmasks on the slice they are drawn on. In comparison, the [3D cylinder brush](#3d-cylinder-brush) is applied to multiple slices, giving it depth in addition to width.

You can adjust the brush tool by:

* Changing the size of the brush.
* Changing between 2D and [3D cylinder brush](#3d-cylinder-brush) modes.

Click **Apply label** or press <kbd>Enter</kbd> to apply the Bitmask.

#### 3D cylinder brush

<div>
  <img />
</div>

The 3D cylinder brush lets you apply a Bitmask in 3 dimensions, which means it is applied to multiple slices in a volume. The following two settings are available:

* The *Size* determines the diameter of the Bitmask brush.
* The *Height* determines the thickness of the 3D Bitmask, measured in number of slices.

Adjust the slider to set your desired *Size* and *Height*.

After the Bitmask is applied, click **Apply label** or press <kbd>Enter</kbd> to apply the Bitmask.

<Tip>
  We recommend [enabling 3D view](#3d-volume-rendering) in one of the windows of the Label Editor when using the 3D cylinder brush. This allows you to see the Bitmask label in 3D.

  1. Select the Bitmask object and select the 3D cylinder brush.
  2. Create your label in the main annotation window.
  3. Click *Additional controls* and enable the *Full 3D* toggle on a reconstructed view.
</Tip>

<div>
  <img />
</div>

#### Panoptic mode

<div>
  <img />
</div>

Panoptic settings allow you to determine how different bitmasks interact with one another.

* **None**: Overlapping bitmasks are allowed. The bitmask overlaps with existing bitmasks.
* **Exclude**: Areas already covered by a bitmask are excluded from the bitmask.
* **Overwrite**: Areas already covered by a bitmask are overwritten by the new bitmask.

#### Thresholding

The *Thresholding* tool enables you to set a threshold that determines the parts of the image or frame that is labeled by the Bitmask. Consequently, only the parts of the image falling within th predefined range are labeled upon selection with the *Thresholding* tool, ensuring precise and targeted labeling.

<div>
  <img />
</div>

When *Thresholding* is enabled, a mask covering the parts of the image that fall above the set threshold appears on the slice. This allows you to preview which parts of the image are labeled when a Bitmask label is applied. The mask color can be changed by clicking the circle icon.

The eyedropper tool enables you to pick a color or intensity value directly from the image.

Three different kinds of threshold can be selected using a dropdown:

* **Intensity**: Only pixels within the set intensity value range are labeled.
* **RGB**: Only pixels within the set [red, green, and blue](https://en.wikipedia.org/wiki/RGB_color_model) range are labeled. The range for each color can be set separately.
* **HSV**: Only pixels within the set [hue, saturation, and value](https://learn.leighcotnoir.com/artspeak/elements-color/hue-value-saturation/) range are labeled.

When your label is ready, click **Apply label**, or press <kbd>Enter</kbd>.

#### Polygon mode

*Polygon mode* lets you draw bitmasks the same way you draw [polygons](#polygon).

<div>
  <img />
</div>

To draw a bitmask using *Polygon mode* :

1. Select *Polygon mode* in the bitmask pop up.
2. Click the editor canvas to start drawing your bitmask.
3. Draw your shape by clicking each time you want to create a vertex.
4. Click the first vertex to complete the shape.

<div>
  <img />
</div>

<Tip>Double-clicking while drawing your bitmask completes the shape by drawing a straight line between the first and last vertices. </Tip>

#### Eraser

The *Eraser* tool allows you to erase parts, or the entirety of your Bitmask selection, if the **Apply label** button has not been clicked yet.

To select the threshold brush, click the eraser icon, or hit <kbd>h</kbd> on your keyboard while the popup is open.

#### Combine bitmasks on an image/frame

Combining bitmasks on an image or frame allows you to label objects that are split/separated in the image/video frame.

<Note>
  When creating a bitmask, the process continues until you press the <kbd>ENTER</kbd> or <kbd>ESC</kbd> key. This allows you to easily create complex bitmask labels without interruption.
</Note>

**To combine two or more bitmasks on an image / video frame:**

1. Hold <kbd>SHIFT</kbd>.

2. Click the bitmasks you want to combine in the Label Editor workspace.

3. Right-click (on Mac press <kbd>Cmd</kbd>).
   A menu appears.

4. Select **Combine bitmasks into**.
   The bitmasks are now a single bitmask.

#### Bitmask overlap management

It is possible to prevent a Bitmask label from being overlapped by subsequent Bitmasks after the label is created. Use the toggle in the *Labels* section of the Label Editor to set the overlap behavior.

<div>
  <img />
</div>

Choose between the following settings:

<img />

* **Can be drawn over** -  If the Bitmask is drawn over, any part of the image beneath the existing Bitmask that falls within the specified threshold range is included in the next label.

<img />

* **Cannot be drawn over** - No part of the image covered by this Bitmask is included in any other Bitmask labels.

<img />

* **Must be drawn over** - If the Bitmask is drawn over, any part of the Bitmask label is included in the new Bitmask, regardless of threshold values set.

#### Updating Bitmask labels

To update a Bitmask label:

1. Click the Bitmask label you would like to edit.
2. Select either the [brush](#brush-tool), [threshold brush](#threshold-brush), or [eraser](#eraser) tool and make your changes.
3. Press <kbd>Enter</kbd> or click the **Update label** button in the Bitmask popup.

#### Moving Bitmasks

Bitmask labels can be moved to another location after being created.

1. Click the Bitmask label you want to move.
2. Click and drag the Bitmask to the desired location.
3. Release the Bitmask to confirm the new location.

<img />

***

## Automation

### Interpolation

Encord's interpolation feature uses a proprietary linear interpolation algorithm that runs without using a representational model or matching pixel information in neighboring frames.

Our interpolation algorithm has been built with pragmatic usage in mind. For example, unlike other linear interpolation methods, Encord's interpolation algorithm does not require a matching number of vertices between objects in set keyframes. Our algorithm also allows you to draw object vertices in arbitrary directions (e.g., clockwise, counterclockwise, and otherwise).

<div>
  <img />
</div>

You can read more about interpolation <a href="/platform-documentation/Annotate/automated-labeling/annotate-interpolation">here</a>.

***

### Import model predictions

Encord's [Python SDK](/sdk-documentation/getting-started-sdk/installation-sdk) allow you to import model predictions programmatically. Importing model predictions helps to pre-annotate your data to save annotation costs.

***

### Cross-series localizer lines

When you work with a DICOM study that contains multiple series — for example, axial, sagittal, and coronal acquisitions — localizer (scout) lines show you exactly where the active tile's current slice intersects the other series displayed in the editor. This lets you instantly correlate a slice position across series without manually mapping between panels.

**How to enable localizer lines**

Click the **Show cross-series localizer lines** icon button in the editor header toolbar to toggle localizer lines on or off. The icon highlights in the Encord primary color when the feature is active. Encord saves your toggle state between sessions.

**How localizer lines work**

* Encord draws colored overlay lines on each non-active series tile showing where the active tile's current slice projects onto that series.
* Each peer series receives a distinct color so you can identify which line corresponds to which series.
* The active tile itself does not display a localizer line — lines appear only on the peer (non-active) tiles.
* Lines update dynamically as you scroll through slices in the active tile.
* Localizer lines respect any canvas rotation you have applied to each tile.

**Thick-slab series**

For thick-slab series, two additional semi-transparent lines flank the center line to indicate the slab thickness extent.

<Note>Localizer lines require DICOM spatial metadata — specifically `ImageOrientationPatient`, `ImagePositionPatient`, and pixel spacing — to be present in the series. If this metadata is absent, no lines appear. Localizer lines only display between series that share the same DICOM Study UID.</Note>

***

## DICOM editor settings

The Label Editor has several DICOM specific settings.

<div>
  <img />
</div>

* **MRP layout**: Enable or disable reconstructed [MPR views](#multiplanar-reconstruction-mpr) for DICOM volumes.
* **Mammography layout**: Select how mammography files are displayed in the editor.
* **Cache DICOM files locally**: Choose whether to cache DICOM files locally.
* **Display DICOM crosshairs**: Shows crosshairs on all windows in the editor when [crosshair navigation](#crosshair-navigation) is enabled.
* **Native resolution rendering**: Displays DICOM files at their original quality and size. We recommend this setting for mammography files.
* **Full localizer line box**: Controls how [cross-series localizer lines](#cross-series-localizer-lines) render on peer series tiles. When off (default), Encord draws only the longest edge of the projected slice rectangle as a single clean line. When on, Encord draws the full projected slice outline (a box or trapezoid shape), similar to Horos-style rendering. This setting is only visible for medical imaging projects.


# Labeling Documents
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-documents



## Label Editor Document Support

The Label Editor supports the following document file types:

* PDF (.pdf)

### Document Label Support

Documents support the following label types:

* Bounding boxes
* Rotatable bounding boxes
* Polylines
* Object primitives
* Keypoint
* Polygons
  <Tip>Polygons support the **PDF text** option on text attributes in your Ontology. This feature automatically populates the text attribute with the text specified by the polygon.</Tip>
* Classifications

<Note>Bitmasks are not available for PDF files.</Note>

<Tip>
  * We recommend adding attributes to your label types when creating your Ontology for labeling documents.
  * The color you specify for each object label in your Ontology can make a big difference in the ease and effectiveness of labeling items. For example, lighter colors are more difficult to see on a white background.
</Tip>

## Label Documents

**Label display** settings can help provide a better labeling experience for each annotator.

<iframe title="YouTube video player" />

<Tip>Press and hold the <kbd>SHIFT</kbd> key while using your mouse/trackpad to move around each page of a document.</Tip>

### Label PDFs

Annotate supports the following label types for PDFs:

* Bounding boxes
* Rotatable bounding boxes
* Polylines
* Object primitives
* Keypoint
* Polygons
  <Tip>Polygons support the **PDF text** option on text attributes in your Ontology. This feature automatically populates the text attribute with the text specified by the polygon.</Tip>
* Classifications

<Note>
  - Classifications support being applied on a range of pages in a PDF.
</Note>

<Tip>
  Use the **Show text outline** feature when labeling documents to streamline your annotation process. When used with object label hotkeys, labeling becomes a smooth efficient process.

  <iframe title="YouTube video player" />
</Tip>

#### Polygons

<Tip>Polygons support the **PDF text** option on text attributes in your Ontology. This feature automatically populates the text attribute with the text specified by the polygon.</Tip>

1. Click the **Show text outline** button to enable the feature.

2. Highlight the text you want selected for annotation.

3. Press the hotkey for the polygon object label.

   The polygon appears automatically around the highlighted text.
   <Note>Enabling the *PDF text* feature on a Text attribute on the Polygon object, automatically populates the Text attribute when the label applies.</Note>

4. Continue annotating the PDF.

5. Click **Submit** when you finish annotating the PDF.

<iframe title="YouTube video player" />

#### Bounding Boxes

1. Click the **Show text outline** button to enable the feature.

2. Highlight the text you want selected for annotation.

3. Press the hotkey for the bounding box object label.

   The bounding box appears automatically around the highlighted text.

4. Continue annotating the PDF.

5. Click **Submit** when you finish annotating the PDF.

<iframe title="YouTube video player" />

### Using Relation Text Attributes - PDFs

Relation text attributes link an object to another object. In images or videos this could be linking a chicken's body to its wing. In PDFs or text documents (text or HTML files) this could be linking words with measurements, or linking words with other words.

<Note>
  Your Ontology must MUST contain text attributes with the Relation feature enabled if you want to use relation text attributes.

  ![Add Relation Text Attribute](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/annotate-ontology-link-objects.gif)
</Note>

While annotating, you can create a relationship between any object with a relation text attribute and any other object. After you create a relation between objects a workflow arrow points from the object with the relation text attribute to the other object.

![Link objects](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/annotate-pdf-relationship.gif)

### Using PDF Text Attribute - PDFs

The **PDF text** automatically populates the **text attribute** with the text specified in the **polygon**.

<Note>
  Your Ontology must have the following to use the **PDF text** feature:

  * Polygon
  * Text attribute on the polygon
</Note>

<iframe title="YouTube video player" />


# Images
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-images



The following video goes through the basics of annotating images in the Label Editor.

<div>
  <iframe />
</div>

Encord provides comprehensive support for image annotation. With the image editor, you can:

* Label using any annotation type such as bounding boxes, rotatable boxes, polygons, polylines, keypoints, and primitives.
* Create frame-level & object classifications.
* Object detection and instance segmentation.
* Reduce manual annotations with automation (e.g., importing model predictions) features.

<div>
  <img />
</div>

***

## Task Management

Before getting into the details of the label editor and making annotations, note the following about scheduling annotation work. Annotation is done in the annotation phase of the task management system. To ensure annotation work is saved properly, each labeling task must be properly assigned to an annotator, annotators must always access the task through the **Queue** tab in the Task Management System, and only the assigned annotator works on any given task at any given time.

***

## Annotation types

Objects are annotated using bounding boxes, polygons, polylines, keypoints or primitives. Frames are annotated using classifications. Instantiating objects or classifications in the image editor generates a *UUID* that uniquely identifies that label in the frame.

<Note>Object labels on the 2D canvas display a dark semi-transparent background behind the label text, making them readable against busy or high-contrast image content. When you hover over an annotated object, the label text becomes bold for additional visual distinction. This applies to all annotation types: bounding boxes, rotatable boxes, polygons, polylines, keypoints, bitmasks, primitives, and 2D cuboids.</Note>

Labels can be assigned with static classifications as defined in the specified [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies). Static classifications define the global properties of an object (e.g., the butterfly is of type red admiral and is orange).

You can read more about automation for image annotation <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-images#automation">here</a>.

***

### Bounding box

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a bounding box ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<div>
  <img />
</div>

Creating a bounding box requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a bounding box annotation type. Instantiate a new bounding box label by clicking on the specified class in the 'Classes' menu, or by using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Bounding box labels can be assigned with static classifications should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified bounding box
* Assign a classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>).

***

### Rotatable box

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a rotatable bounding box">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

Traditional bounding boxes are great for annotating objects that appear in horizontal or vertical orientation, however, their accuracy may be limited when it comes to annotating objects at an angle. In such cases, use rotatable boxes to produce more accurate annotations.

Creating a rotatable bounding box requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a rotatable box annotation type.Instantiate a new rotatable box label by clicking on the specified class in the 'Classes' menu or using the specified hotkey. Resize rotatable boxes like normal bounding boxes, and then grab the rotation handle to adjust the position until you're satisfied with the annotation's accuracy, as below.

Rotatable boxes can be assigned static classifications should they be defined in your Ontology,\
and you can [export the labels as usual](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels).

***

### Polygon

<AccordionGroup>
  <Accordion title="Watch a tutorial for working with polygons">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

Polygons are often necessary if you want to train your applications on the tightest object boundaries. Creating a polygon requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a polygon annotation type. Enable or disable free-hand drawing mode by pressing <kbd>d</kbd> on your keyboard. Polygon coarseness for polygons drawn free-hand is set in the 'Settings' drawer in the *Drawing settings* drop-down. Instantiate a new polygon label by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

A polygon can be closed by double-clicking anywhere on the canvas. Doing so will "snap" creating an edge between the last vertex to the first vertex drawn.

You can create a polygon using SAM 2, by placing vertices, or by using the polygon brush (<kbd>F</kbd>).

Polygon labels can be assigned static classifications should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the **+** icon or start/end frame in the range overview for the specified polygon
* Assign a classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>)

<div>
  <img />
</div>

***

### Polyline

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a polyline">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

Creating a polyline requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a polyline annotation type. Enable or disable free-hand drawing mode by pressing <kbd>d</kbd> on your keyboard. Polyline coarseness for polylines drawn free-hand is set in the 'Settings' drawer in the *Drawing settings* drop-down. Instantiate a new polyline label by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

When free-hand drawing is off, each mouse click places a point on the polyline. A polyline needs at least two points. Double-click anywhere on the canvas to finish, but note that the double-click doesn't add a point or affect the shape. If only one point is placed, the polyline is canceled. Make sure to click at least twice before double-clicking to complete the shape.

Polyline labels can be assigned with static classifications should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified polyline
* Assign a classification by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>)

***

### Keypoint

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a keypoint">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<div>
  <img />
</div>

Creating a keypoint requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a keypoint annotation type. Instantiate a new keypoint label by clicking on the specified class in the 'Classes' menu or using the specified\
hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Keypoints labels can be assigned with static classifications should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified keypoint
* Assign classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>)

***

### Primitives

<div>
  <img />
</div>

Creating a [primitive](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#object-primitives) requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a primitive annotation\
type. Use primitives to templatize shapes (e.g., 3D cuboids, pose estimation skeletons) commonly\
used by your annotation team.

Instantiate a new primitive label by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Object primitives allow you to define properties of edges defined in your template as visible, occluded, or invisible. Toggle the edge property settings for a primitive by highlighting the primitive and clicking the *Show controls* button.

Primitive labels can be assigned with static classifications should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified primitive
* Assign classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>)

***

### Segmentation masks / Bitmasks

<div>
  <iframe />
</div>

Bitmasks allows you to create labels using a brush tool to select parts of an image. This can be useful when creating labels for vessel outlines, or labeling topologically separate regions belonging to the same frame classification.

When creating a bitmask, the process continues until you press the <kbd>ENTER</kbd> or <kbd>ESC</kbd> key. This allows you to easily create complex bitmask labels without interruption.

<div>
  <img />
</div>

<Note>Creating a bitmask segmentation requires an Ontology with the *Bitmask* annotation type.</Note>

<Tip>[Existing Bitmask labels can be updated](#updating-bitmask-labels) using the [brush tool](#brush-tool), [threshold brush](#threshold-brush), and [eraser](#eraser) tools.</Tip>

#### Brush tool

When you select your bitmask annotation type, the brush tool is selected by default. You can adjust the size of the Bitmask brush tool using the slider in the Bitmask popup, as seen in the screenshot above.

The brush tool can be selected by clicking the brush icon, or by pressing <kbd>f</kbd> on your keyboard while the popup is open.

When your label is ready, click **Apply label**, or press <kbd>Enter</kbd>.

#### Panoptic mode

<div>
  <img />
</div>

Panoptic settings allow you to determine how different bitmasks interact with other bitmasks, polygons, and SAM created labels.

Use panoptic *Exclude* mode to automatically exclude existing bitmasks from new segmentations. This prevents overlapping labels and ensures clean, non-overlapping annotations.

<Note>
  Panoptic mode only works with bitmask annotations and is automatically applied when using manual label creation.
</Note>

* **None**: Overlapping bitmasks are allowed. The bitmask overlaps with existing bitmasks, polygons, and SAM created labels.
* **Exclude**: Areas already covered by a bitmask are excluded from the bitmasks, polygons, and SAM created labels.
* **Overwrite**: Areas already covered by a bitmask are overwritten by the new bitmasks, polygons, and SAM created labels.

#### Thresholding

The *Thresholding* tool enables you to set a threshold that determines the parts of the image or frame that is labeled by the Bitmask. Consequently, only the parts of the image falling within th predefined range are labeled upon selection with the *Thresholding* tool, ensuring precise and targeted labeling.

<div>
  <img />
</div>

When *Thresholding* is enabled, a mask covering the parts of the image that fall above the set threshold appears on the slice. This allows you to preview which parts of the image are labeled when a Bitmask label is applied. The mask color can be changed by clicking the circle icon.

The eyedropper tool enables you to pick a color or intensity value directly from the image.

Three different kinds of threshold can be selected using a dropdown:

* **Intensity**: Only pixels within the set intensity value range are labeled.
* **RGB**: Only pixels within the set [red, green, and blue](https://en.wikipedia.org/wiki/RGB_color_model) range are labeled. The range for each color can be set separately.
* **HSV**: Only pixels within the set [hue, saturation, and value](https://learn.leighcotnoir.com/artspeak/elements-color/hue-value-saturation/) range are labeled.

When your label is ready, click **Apply label**, or press <kbd>Enter</kbd>.

#### Eraser

The *Eraser* tool allows you to erase parts, or the entirety of your Bitmask selection if the **Apply label** button has not been clicked yet.

To select the threshold brush, click the eraser icon, or press <kbd>h</kbd> on your keyboard while the popup is open.

#### Combine bitmasks on an image/frame

Combining bitmasks on an image or frame allows you to label objects that are split/separated in the image/video frame.

<Note>
  When creating a bitmask, the process continues until you press the <kbd>ENTER</kbd> or <kbd>ESC</kbd> key. This allows you to easily create complex bitmask labels without interruption.
</Note>

**To combine two or more bitmasks on an image / video frame:**

1. Hold <kbd>SHIFT</kbd>.

2. Click the bitmasks you want to combine in the Label Editor workspace.

3. Right-click (on Mac press <kbd>Cmd</kbd>).
   A menu appears.

4. Select **Combine bitmasks into**.
   The bitmasks are now a single bitmask.

#### Bitmask overlap management

It is possible to prevent a Bitmask label from being overlapped by subsequent Bitmasks after the label is created. Use the toggle in the *Labels* section of the Label Editor to set the overlap behavior.

<div>
  <img />
</div>

Choose between the following settings:

<img />

* **Can be drawn over** -  If the Bitmask is drawn over, any part of the image beneath the existing Bitmask that falls within the specified threshold range is included in the next label.

<img />

* **Cannot be drawn over** - No part of the image covered by this Bitmask is included in any other Bitmask labels.

<img />

* **Must be drawn over** - If the Bitmask is drawn over, any part of the Bitmask label is included in the new Bitmask, regardless of threshold values set.

<Note>The  **Must be drawn over**  setting for *Bitmask overlap* is only available to select customers. Contact [support@encord.com](mailto:support@encord.com) for more information.</Note>

#### Updating bitmask labels

To update a bitmask label:

1. Click the bitmask label you want to edit.
2. Select either the [brush](#brush-tool), [threshold brush](#threshold-brush), or [eraser](#eraser) tool and make your changes.
3. Press <kbd>Enter</kbd> or click the **Update label** button in the bitmask popup.

#### Moving bitmasks

Bitmask labels can be moved to another location after being created.

1. Click the bitmask label you want to move.
2. Click and drag the bitmask to the desired location.
3. Release the bitmask to confirm the new location.

<img />

***

#### Downloading bitmasks as PNG

You can download one or more bitmask annotations as a PNG image directly from the Label Editor using the right-click context menu. Each bitmask renders in its assigned annotation color in the exported file.

The Label Editor names downloaded files using the pattern: `<data_title>_frame_<frame_index>_<label>.png`. Special characters in the data title are replaced with underscores.

<Note>The download options only appear for bitmask-type annotations. Non-bitmask shapes do not show these options in the context menu.</Note>

There are three ways to download bitmasks as PNG:

* **Single bitmask** — Right-click a bitmask annotation and select **Download bitmask as image**. The filename includes the annotation name and object ID.
* **Multiple bitmasks** — Select multiple bitmask annotations, then right-click and select **Download bitmasks as image**. The editor composites all selected bitmasks into a single PNG file.
* **All bitmasks on the current frame** — Right-click the canvas background and select **Download all bitmasks as image**. This option appears only when at least one bitmask exists on the current frame. The editor composites all bitmasks on the frame into a single PNG file.

<Info>If the download fails, the editor displays an error notification.</Info>

***

### Frame classification

Creating frame classification(s) requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a classification annotation type. Frame-level classifications consider the frame as a whole, not any given object's localization. Instantiate a frame-level classification label by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Encord currently supports radio, checklist, and free-form text input classification types. Edit existing classification labels by clicking on the **+** icon for the specified label.

<div>
  <img />
</div>

<div>
  <i>1. Create a frame classification from ontology 2. Edit a classification</i>
</div>

### Linking object instances

<Note>Object instances are linked using *Relation* attributes, which are set up in the Ontology. See our [documentation on *Relation* attributes](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#relation-attributes) to learn more.</Note>

1. Create both instance labels. In this example a chicken and its wing have been labeled using bounding boxes.

2. Click the *Edit classifications* button for the object with the *Relation* attribute. In the example this object is the wing, as seen below.

<img />

3. Click the *Set relation...* bar and select the instance you want to link the selected instance to. In our example the chicken and the wing appear on the same frame, and therefore appear under the *This frame* heading. Instances in different frames will appear under the heading *Rest*.

<img />

4. Click **Done**. The instances are now linked. This is shown in the *Instance labels* section with the name of the linked instance being displayed.

<img />

***

## Automation

### Import model predictions

Encord's [Python SDK](/sdk-documentation/getting-started-sdk/installation-sdk) & APIs allow you to import model predictions programmatically. Importing model predictions helps to pre-annotate your data to save annotation costs.

***

### Automated labeling

See our documentation on automated labeling [here](/platform-documentation/Annotate/automated-labeling).


# Label Editor - Annotation
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate



<Info>To ensure seamless data loading in Encord, allowlist [https://app.encord.com/](https://app.encord.com/) or [https://app.us.encord.com/](https://app.us.encord.com/) in any 3rd party VPNs, firewalls, or URL isolators. This helps to prevent potential issues with opening your data in Encord.</Info>

This documentation provides a comprehensive guide to using the Label Editor for annotation, covering its components, features, and the display of various elements.

For information on how to label, see our [documentation here](/platform-documentation/GettingStarted/gettingstarted-labeling).

## Annotation Mode

### Introductory Video Tutorials

The following video goes through the basics of annotating visual data in the Label Editor.

<div>
  <iframe />
</div>

<Tip>Check out our [Video Tutorials page](/platform-documentation/General/video-tutorials) for more introductory videos!</Tip>

***

<div>
  <img />
</div>

**Annotation mode components**:

* **A**. [Editor menu](#editor-menu)
* **B**. [Quick toolbar](#quick-toolbar)
* **C**. [Classes](#classes)
* **D**. [Instances and Frame labels](#instances-and-frame-labels)
* **E**. [Automated labeling](#automated-labeling)
* **F**. [Editor timeline (for videos and image sequences only)](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#editor-timeline)
* **G**. Annotation canvas: displays the media asset and provides interface for drawing and editing labels.
* **H**. [Editor header](#editor-header)
* **I**. [Skip or Submit](#skip-or-submit-labels)

***

### Copy / Paste Labels & Instances

Using the copy and paste features in the Label Editor can significantly save time and effort. Here's how you can efficiently use these features:

* **Copy**: To copy both the label and the instance, use the keyboard shortcut <kbd>CMD</kbd> + <kbd>C</kbd> on Mac or <kbd>Ctrl</kbd> + <kbd>C</kbd> on Windows.

* **Paste instance**: To paste the copied instance, use <kbd>CMD</kbd> + <kbd>V</kbd> on Mac or <kbd>Ctrl</kbd> + <kbd>V</kbd> on Windows. Instances can only be pasted onto a different frame from where they were copied.

* **Paste Label**: To paste just the label / shape, use <kbd>CMD</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> on Mac or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> on Windows. Labels can be pasted onto any frame.

* **Clear Cuboid**: To clear a copied 3D cuboid, use <kbd>CMD</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd> on Mac or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd> on Windows with nothing selected.

***

### Bulk Label Operations

Fixing incorrect labels is an important step in producing high-quality datasets. With bulk label operations, annotators can merge labels which should really be one instance, or efficiently delete multiple labels in bulk.

Bulk label operations are accessed in the [editor menu](#editor-menu).

**Merge operations**

Merge one or more label objects into a single object.

1. Select all objects to be merged in the *Select objects to be merged* drop-down menu.
2. Select the target object in the *Select objects to be merged into* field.
3. Click **Merge**.

<div>
  <img alt="Merge objects into a single object" title="merge-operations" />
</div>

**Delete operations**

Encord lets you perform bulk delete operations as follows:

<div>
  <img alt="delete labels in bulk" title="Delete-operations" />
</div>

**Remove labels of a specific class**:

1. Select a class to delete from the *Select class menu*.
2. Specify the frame range.
3. Click the **Delete** button.

**Delete all labels within a frame range**:

1. Navigate to the *Delete all labels from range* section.
2. Set a range to delete labels from.
3. Click **Delete**.

**Delete labels below a specified confidence level**:

1. Navigate to the *Delete labels below confidence* section.
2. Set the minimum confidence threshold. All labels with a [confidence value](#confidence-score) below this threshold are deleted.
3. Specify a range of frames to delete the specified labels from.
4. Click **Delete**.

***

### Classes

In annotation mode, the *Classes* section of the Label Editor shows you the available Ontology classes, both objects and classifications. You can create a new instance by either clicking the desired class, or by using the indicated instantiation hotkeys. Learn more about Ontologies in general [here](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) or learn more about the details of [Ontology structure on Encord](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#ontology-structure).

***

### Instances and Frame labels

The canvas is your labeling area to annotate the *instances* of the Ontology classes.

* An instance is a specific occurrence of a class. For example, if you have a class called "Car", an instance of this class could be "Car(0)", which might represent a specific black sedan. This single instance can appear in a single frame or a range of frames, and therefore, instances may contain multiple labels across frames. You can think of an instance as a unique object that belongs to a certain class.

* A frame label is a frame-specific annotation of an instance. For example, the annotation of "Car(0)" on frame 201 is a label. Labels are used to annotate instances in specific frames, providing more detailed information about the instance in the context of that frame.

<Tip>You can group instances of the same class together using the *Group by class* button.</Tip>

***

### Skip or Submit labels

**Submit tasks**

Labels are applied in the Label Editor. Click the **Submit** button to submit your labels for review.

<div>
  <img />
</div>

**Skip tasks**

Users have the option to skip tasks in cases where, for example, the file is blurred, or if they suspect the task was erroneously added.

<Info>
  Skipping a task automatically creates an [Issue](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#issues-and-comments) and is therefore counted in the [Issue Analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues).
</Info>

When a user skips a task, it is automatically unassigned from them, and the task's status is updated to *Skipped*. If another task is available, it automatically opens in the Label Editor and is assigned to the user.

1. Click the **Skip** button to skip an annotation task.

<div>
  <img />
</div>

2. A dialog appears. Enter a reason for skipping the task - the reason is added as an [issue](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments) to the task that annotators and reviewers can see. If no reason is entered "This task was skipped" is added by default.

<div>
  <img />
</div>

***

### Turbo mode

Turbo mode simplifies the standard annotation workflow, enabling annotators to rapidly assign or confirm attributes. Activate turbo mode and choose an instance from the top-left dropdown menu to set the instance and its relevant attributes.

<Tip>In turbo mode, the auto-zoom feature automatically focuses the point of view on the active instance as you browse through them. You can adjust the zoom manually to get a better view of the instance's context. The view auto-zooms again when moving to another instance.</Tip>

**Enable turbo mode:**

1. Open the [editor settings](#editor-settings).
2. Use the search bar to search for *Turbo mode*.
3. Enable the *Turbo mode* toggle.

***

### View Annotator Instructions

The **Annotator instructions** button is available in the top-left corner of the Label Editor if annotation instructions are provided by the Admin or Team Manager.

<Tip> To learn how to upload annotation instructions click [here](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#upload-annotation-instructions)</Tip>

<div>
  <img />
</div>

***

### Confidence Score

Each instance or label is assigned a confidence score (denoted with the symbol α) that appears next to the label name.

The confidence score is a measure of a machine learning model's certainty that a given prediction is accurate. The higher the confidence score, the more certain a model is about its prediction.

Manual labels are always assigned α = 100%, while label predictions created using models and automated methods such as interpolation have a confidence score below 100% (α \< 100%).

***

### Labels pane

The *Labels* pane shows all the instantiated objects and classifications for a data unit. Objects are grouped first by class, and sorted by creation time within each class, with earlier objects on top. They are named in an "ABC (0)" format, where ABC is the Ontology class and 0 is the first instance annotation.

<div>
  <img />
</div>

* **A**: Toggle between showing displaying all labels, or only labels in the current frame.
* **B**: Show / Hide details for this instance.
* **C**: The range of frames the instances appears on.
* **D**: Attributes the object has and the frames they appear on.
* **E**: Filter by frame range.
* **F**: Sort label instances.
* **G**: Search for an instance.
* **H**: Show / Hide labels.
* **I**: Show / Hide labels for this instance.
* **J**: Additional actions. Described below.
* **K**: Keyboard shortcut to create a label for this instance.
* **L**:[Edit attributes](#attributes) for this instance.
* **M**: Add a new label for this instance.
* **N**: Toggle auto-annotation for [SAM](/platform-documentation/Annotate/automated-labeling/annotate-sam).

**Click the *three dots* icon to access additional actions:**

<div>
  <img />
</div>

**Copy URL**: Copies the URL for the particular object.

**Copy identifier**: Each object instance is automatically assigned a unique alphanumeric ID, which can be used to identify it within the project. This ID is sometimes known alternately as a *feature hash*, *instance hash*, or *instance identifier*. For objects and classifications, it may also be known as the *object hash* or *classification hash*. Use this button to copy the *instance identifier* to your clipboard -- which may help in workflows using specific instances in source code or for other purposes.

**Track from this frame**: Initiates single object tracking using SAM 2. This type of automated labeling creates labels for the specified object from the current frame, according to the [Single object tracking settings](#single-object-tracking-settings) section in the [editor settings](#editor-settings).

**Interpolate**: Interpolates this object's location for a range between specified frames. See our [documentation on interpolation](/platform-documentation/Annotate/automated-labeling/annotate-interpolation) for more details.

**Go to object**: Navigate to the specified object in the data asset. If it is present in more than one frame, the first frame the object appears is shown.

**Split object track**: In some cases, particularly when many objects overlap, labels may be associated with the correct instance in several frames, but later become associated with a different instance. In those cases, use the *Split object track* feature, which will split the labels from one instance into two at the frame specified.

<div>
  <img />
</div>

**Change class**: Use the drop-down in the modal to change the current class of an instance. You can only switch within classes of the same [annotation type](/platform-documentation/Annotate/annotate-ontologies#objects). For example, you cannot switch from a bounding box to a polygon.

<Tip>
  You can select multiple labels and bulk-change their classes by right-clicking and choosing **Change Class**.
</Tip>

**Delete object**: Delete an object from a single frame or a range of frames. To delete labels between frame ranges, move the frame slider to the desired frames, or input the *From* and *To* (exclusive) values in the relevant form.

### Attributes

The details pane allows you to modify attributes efficiently. For [dynamic attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes), use the 'Preserve chosen state' feature. When this feature is toggled 'ON', any subsequent labels for that instance automatically inherit the same dynamic attribute value as the frame where 'Preserve chosen state' was enabled.

#### Propagate Across Gaps

When you annotate objects that appear only on disjointed frame ranges (for example, an object present on frames 0–10, 20–30, and 40–50), setting a dynamic attribute value normally applies only to the contiguous sub-range containing the current playhead position. The **Propagate across gaps** setting extends this behavior so that the value automatically covers all later occurrences of the object.

<Note>**Propagate across gaps** is off by default. When **Limit to a single frame** is also enabled, it takes precedence and **Propagate across gaps** has no effect.</Note>

**To enable Propagate across gaps:**

1. Open the Timeline settings menu in the video Label Editor.
2. Navigate to the **Dynamic attributes** section.
3. Enable the **Propagate across gaps** toggle.

Once enabled, setting a dynamic attribute at the playhead propagates the value forward through all later sub-ranges of the object, stopping only at the next deliberately-set keyframe for that attribute. For checklist attributes, each option propagates independently — only keyframes for the same checklist option stop propagation of that option.

<Tip>See our [tutorial on adding attributes](/platform-documentation/GettingStarted/gettingstarted-labeling#adding-attributes) for a detailed guide</Tip>

If you have numerous attributes, use the search bar to quickly find specific attributes or attribute values.

<div>
  <img />
</div>

***

### Editor Timeline

<Note>
  The Editor Timeline is only available for videos, image sequences, PCD scenes, and audio files.
</Note>

Double-clicking a range on the timeline plays the corresponding section of the video, scene, or audio file.

#### Bulk Actions

Labels and ranges can be multi selected on the timeline using <kbd>Shift</kbd> + click. Selected regions are shown in the left side of the editor.

<div>
  <img />
</div>

The following actions can be performed:

* **Merge ranges**: Merge the selected ranges into a single range.
* **Play range(s)**: Selecting a range allows you to play the file for just that range. If multiple ranges are selected, the file will play for all of the selected ranges in chronological order.
* **Change class**: Change the class for all labels within the selected range(s).

***

### Automated Labeling

Automated labeling includes several techniques to quickly create labels automatically.

* [Interpolation](/platform-documentation/Annotate/automated-labeling/annotate-interpolation) do not require set up or training, and are always available.
* [SAM 2 Segmentation](/platform-documentation/Annotate/automated-labeling/annotate-sam) creates labels by clicking parts of your frame or image.
* [SAM 2 tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam#sam-2-tracking) tracks objects across a range of frames using the \[SAM 2] model.

1. Click the **Automated labeling** button to open the *Automated labeling* panel.
2. Select the type of automated labeling you want to use.
3. Run automated labeling for the selected objects.

***

### Edit Polygons and Polylines

Encord provides multiple tools to edit polygon and polyline labels after they have been created. See our tutorial video for an quick introduction on working with polygons in Encord.

<AccordionGroup>
  <Accordion title="Watch a tutorial for working with polygons">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Move Vertex">
    **To move vertices**:

    Click and drag a vertex to move it to a new location.
  </Accordion>

  <Accordion title="Add Vertex">
    **To add a vertex**:

    You can add more vertices to a polygon after it has been created.

    1. Click the polygon you want to add a vertex to
    2. Click the position along the edge of the polygon you want to add a vertex. Repeat to add as many vertices as necessary.
  </Accordion>

  <Accordion title="Remove Vertex">
    **To remove a vertex**:

    You can remove the last vertex by pressing the <kbd>Backspace</kbd> key while still in *draw* mode.

    1. Click the polygon you want to remove vertices from
    2. Right-click a vertex to delete it
  </Accordion>

  <Accordion title="Extension Tool">
    Use the polygon freehand tool to modify the edge of a polygon or polyline in a free-hand manner and create complex polygons.

    **To use the freehand tool**:

    1. Right-click the polygon you would like to edit.
    2. Click **Edit with brush** or press the <kbd>J</kbd> hotkey.
       A floating brush tool menu appears.
    3. Adjust the brush size to suit your needs.
    4. Mouse over location you would like to start editing from, and click and hold to start the edit process.
    5. Drag the cursor freely to draw out the new polygon edge let go of mouse to finish editing.
  </Accordion>

  <Accordion title="Eraser Tool">
    Use the eraser tool to remove any part of a polygon in a free-hand manner.

    <div>
      <img />
    </div>

    **To use the eraser tool**:

    1. Right-click the polygon you would like to edit.
    2. Click **Edit with brush** or press the <kbd>G</kbd> hotkey.
       A floating brush tool menu appears.
    3. Select the eraser tool.
    4. Adjust the brush size to suit your needs.
    5. Mouse over location you would like to start editing from, and click and hold to start the edit process.
    6. Drag the cursor freely to draw out the new polygon edge let go of mouse to finish editing.
  </Accordion>

  <Accordion title="Merge Polygons">
    Merging polygons combines two polygons into a single polygon

    **To merge Polygons**:

    1. Right-click the polygon you would like to edit.
    2. Click **Merge with another polygon**.
    3. Click the polygon you want to merge with.

    The polygons have been merged.
  </Accordion>

  <Accordion title="Subtract Polygons">
    Subtracting polygons removes the area one polygon from that of another.

    **To subtract polygons**:

    1. Right-click the polygon you would like to edit.
    2. Click **Subtract another polygon**.
    3. Click the polygon you want to subtract from your selected polygon.

    The part of the second polygon that intersected the first is now removed from the first polygon.
  </Accordion>

  <Accordion title="Polygon Brush">
    The Polygon brush allows you to create polygons in the same manner that bitmasks can be created with the brush tool.

    **To create polygons with the brush:**

    1. Click the polygon object from the left pane.
       The polygon tool dialog appears.
    2. Press <kdb>F</kdb> or click the **Brush** icon.
    3. Adjust the size and shape of the brush.
    4. Draw the polygon you need on the data unit in the Label Editor.
    5. Press <kdb>ENTER</kdb> to complete the polygon.
  </Accordion>

  <Accordion title="Freehand Edge Touchup">
    Freehand edge touchup lets you refine a polygon by drawing a new edge between two vertices to adjust and close its shape.

    <div>
      <img />
    </div>

    **To use freehand edge touchup**:

    1. Right-click the polygon you want to edit.
    2. Select **Freehand edge touchup** or press the <kbd>F</kbd> hotkey.
    3. Click the starting vertex for your new edge.
    4. Move the cursor to the target vertex where you want to close the shape.
    5. Click to finalize the edit.
  </Accordion>
</AccordionGroup>

### Editor Canvas Interactions

**Shape-specific interactions**:

| Shape    | Interactions                                                                                          | Modalities                                   |
| -------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Bitmask  | Ability to move (one or multiple)                                                                     | Video / Image Group / Image Sequence / DICOM |
|          | Ability to ‘select multiple’ with <kbd>Shift</kbd> + click                                            | Video / Image Group / Image Sequence / DICOM |
|          | Draw using polygon ‘pen’                                                                              | Video / Image Group / Image Sequence / DICOM |
|          | [Panoptic mode](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#panoptic-mode) | Video / Image Group / Image Sequence / DICOM |
| Polygon  |                                                                                                       | Video / Image Group / Image Sequence / DICOM |
|          | Add vertex with left-click                                                                            | Video / Image Group / Image Sequence / DICOM |
|          | Remove vertex with right-click                                                                        | Video / Image Group / Image Sequence / DICOM |
|          | Use the Brush tool by pressing <kbd>F</kbd>                                                           | Video / Image Group / Image Sequence / DICOM |
| Polyline |                                                                                                       | Video / Image Group / Image Sequence / DICOM |
|          | Add vertex with left-click                                                                            | Video / Image Group / Image Sequence / DICOM |
|          | Remove vertex with right-click                                                                        | Video / Image Group / Image Sequence / DICOM |

**Right-click interactions**:

| Shape                  | Right-click Interactions        | Modalities                                     |
| ---------------------- | ------------------------------- | ---------------------------------------------- |
| Bounding Box           | Track from this frame           | Videos, image groups, and image sequences only |
| Bounding Box           | Interpolate                     | Videos, image groups, and image sequences only |
| Bounding Box           | Split object track              | All                                            |
| Bounding Box           | Change class                    | All                                            |
| Bounding Box           | Copy identifier                 | All                                            |
| Bounding Box           | Delete object                   | All                                            |
| Bounding Box           | Copy URL                        | All                                            |
| Rotatable Bounding Box | Track from this frame           | Videos, image groups, and image sequences only |
| Rotatable Bounding Box | Interpolate                     | Videos, image groups, and image sequences only |
| Rotatable Bounding Box | Split object track              | All                                            |
| Rotatable Bounding Box | Change class                    | All                                            |
| Rotatable Bounding Box | Copy identifier                 | All                                            |
| Rotatable Bounding Box | Delete object                   | All                                            |
| Rotatable Bounding Box | Copy URL                        | All                                            |
| Polygon                | Interpolate                     | All                                            |
| Polygon                | Split object track              | All                                            |
| Polygon                | Change class                    | All                                            |
| Polygon                | Copy identifier                 | All                                            |
| Polygon                | Delete object                   | All                                            |
| Polygon                | Copy URL                        | All                                            |
| Polygon                | Track from this frame           | Videos                                         |
| Polygon                | Edit with brush                 | All                                            |
| Polygon                | Freehand edge touchup           | All                                            |
| Polygon                | Merge with another polygon      | All                                            |
| Polygon                | Subtract another polygon        | All                                            |
| Polyline               | Track from this frame           | Videos, image groups, and image sequences only |
| Polyline               | Interpolate                     | Videos, image groups, and image sequences only |
| Polyline               | Split object track              | All                                            |
| Polyline               | Change class                    | All                                            |
| Polyline               | Copy identifier                 | All                                            |
| Polyline               | Delete object                   | All                                            |
| Polyline               | Copy URL                        | All                                            |
| Polyline               | Freehand edge touchup           | All                                            |
| Keypoint               | Track from this frame           | Videos, image groups, and image sequences only |
| Keypoint               | Interpolate                     | Videos, image groups, and image sequences only |
| Keypoint               | Split object track              | All                                            |
| Keypoint               | Change class                    | All                                            |
| Keypoint               | Copy identifier                 | All                                            |
| Keypoint               | Delete object                   | All                                            |
| Keypoint               | Copy URL                        | All                                            |
| Bitmask                | Interpolate                     | Videos, image groups, and image sequences only |
| Bitmask                | Change class                    | All                                            |
| Bitmask                | Copy identifier                 | All                                            |
| Bitmask                | Delete object                   | All                                            |
| Bitmask                | Copy URL                        | All                                            |
| Bitmask                | Select more bitmasks to combine | All                                            |
| Bitmask                | Download bitmask as image       | All                                            |
| Bitmask                | Track from this frame           | Videos                                         |
| Object Primitive       | Track from this frame           | Videos, image groups, and image sequences only |
| Object Primitive       | Interpolate                     | Videos, image groups, and image sequences only |
| Object Primitive       | Change class                    | All                                            |
| Object Primitive       | Copy identifier                 | All                                            |
| Object Primitive       | Delete object                   | All                                            |
| Object Primitive       | Copy URL                        | All                                            |

***

## Multi-Select Panel

When you select multiple annotations in the Label Editor, a specialized multi-select panel appears in the left sidebar. This panel provides a streamlined interface for managing multiple selected objects and classifications simultaneously.

### Overview

The multi-select panel displays when you have two or more annotations selected and offers:

* A count of selected items displayed in a pill badge
* A list of all selected objects and classifications with their names
* Individual deselection controls for each item
* Bulk actions that can be applied to all selected annotations

### Using the Multi-Select Panel

<Steps>
  <Step title="Select multiple annotations">
    Hold **Shift** and click on multiple objects or classifications in the canvas or labels pane to select them.
  </Step>

  <Step title="View selected items">
    The multi-select panel automatically appears in the left sidebar, showing the count of selected items and listing each annotation by name.
  </Step>

  <Step title="Deselect individual items">
    Click the **X** button next to any annotation name to remove it from the selection.
  </Step>

  <Step title="Apply bulk actions">
    Use the available bulk actions to perform operations on all selected annotations at once.
  </Step>
</Steps>

<Note>The multi-select panel is available for both objects (bounding boxes, polygons, etc.) and classifications, allowing you to work with mixed selections efficiently.</Note>

### Multi-Select Panel Features

**Selected item display**: Each selected annotation appears as a row showing:

* The annotation name and type
* Frame range information where the annotation appears
* A close button to deselect individual items

**Bulk operations**: When multiple items are selected, you can perform actions like:

* Bulk deletion
* Class changes
* Attribute modifications

<Tip>The multi-select panel makes it easy to manage complex annotations by providing a clear overview of your current selection and quick access to bulk editing tools.</Tip>

## Label Branches

Label branches let you keep multiple versions of a Project's labels side-by-side. Use them to preserve a labeled state before a re-labeling pass, run an experiment without disturbing `main`, or hold a reviewer-only copy of labels.

<a href="https://www.loom.com/embed/795d49df662946d0b85bad2adc57ae2a" aria-label="Watch: Create & Display label branches" />

### Create Label Branches

Label branches are created in the [Label Checkpoint Workflow stage](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#branch-overlay-labels), or using the [SDK](/sdk-documentation/sdk-labels/sdk-label-versioning).

### View Label Branches

<div>
  <img />
</div>

<Note>
  This feature is only available to Workspace and Project Admins, and Team Managers in the REVIEW and COMPLETE Workflow stages.
</Note>

**To view labels from other branches:**

1. Click the **Branches** button in the Label Editor header.
   The branch overlay panel opens.

2. Select the checkboxes for the branches you want to overlay.
   Each branch displays with a unique color indicator.

3. Click outside the panel to close it.
   The selected branch labels now appear as read-only overlays in the 3D scene.

<Note>
  Branch label comparison is available in Review and Complete editor views — no feature flag or admin configuration required. Overlay labels are read-only. You cannot edit annotations from other branches directly in the overlay view.
</Note>

<Info>Audio and text-document modalities do not yet display branch names on overlay labels. The vertical fan-out uses fixed pixel offsets and is not collision-aware; in very dense scenes with many overlapping annotations, labels from multiple branches may still be difficult to read.</Info>

***

## Multi-Tile Label Operations

<Info>In Projects with multiple data tiles, label operations (tracking, interpolation, and deletion) now target the specific tile where the label is located, ensuring accurate operations across different data sources.</Info>

When working with Projects that contain multiple data tiles, the Label Editor automatically handles label operations based on the tile context. This means:

* **Tracking operations** apply to objects within their specific tile
* **Interpolation** works within the correct tile's frame range
* **Label deletion** removes labels from the appropriate tile
* **Navigation** automatically switches to the correct tile when needed

This tile-aware behavior ensures that your annotations remain accurate and operations are performed on the intended data, even when working with complex multi-tile projects.

***

## Download Bitmask Annotations as PNG

You can download bitmask annotations directly from the Label Editor as PNG image files without running a full project export. Each downloaded PNG renders the bitmask in its assigned annotation color.

**Download a single bitmask**

Right-click a bitmask annotation on the canvas and select **Download bitmask as image**. The editor downloads a PNG file for that bitmask.

**Download multiple selected bitmasks**

Select two or more bitmask annotations (hold <kbd>Shift</kbd> and click each one), then right-click any selected bitmask and choose **Download bitmasks as image**. The editor composites all selected bitmasks into a single PNG file.

**Download all bitmasks on the current frame**

Right-click anywhere on the canvas background (not on an annotation) and select **Download all bitmasks as image**. This option appears only when at least one bitmask annotation exists on the current frame. The editor composites all bitmasks on the frame into a single PNG file.

<Note>The **Download bitmask as image** and **Download bitmasks as image** options appear only for bitmask-type annotations. Non-bitmask shapes do not show these options in their context menus.</Note>

**Downloaded file naming**

Encord names downloaded PNG files using the following pattern:

`<data_title>_frame_<frame_index>_<label>.png`

* Special characters in the data title are replaced with underscores.
* For a single bitmask, `<label>` uses the annotation name and object ID.
* For multiple selected bitmasks, `<label>` is `bitmasks`.
* For the canvas-level download, `<label>` is `all_bitmasks`.

<Info>If a download fails, the editor displays an error notification.</Info>

***

## Controls Common To Both Modes

### Editor Timeline

The Editor timeline visualizes when objects and instances appear throughout videos, scenes, and audio files. The cursor tracks playback in real time, always reflecting the current frame. The timeline is shown by default and can be resized or hidden by dragging it up or down.

***

### Editor Header

<div>
  <img alt="Editor header menu" title="editor header" />
</div>

The Editor header at the top-right of the navigation bar contains buttons and menu items to perform labeling activities as well as manage general app settings and notifications.

| **Icon** | **Name**               | **Description**                                                                                                                                    |
| -------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img />  | Help                   | Links to the: quick start guide, documentation, learning hub, and Encord support team.                                                             |
| <img />  | Notifications          | Shows the current status and history of actions taken in the application. This includes uploading datasets, training models, and exporting labels. |
| <img />  | Share                  | Copies the URL of the asset currently being labeled or reviewed.                                                                                   |
| <img />  | Save labels            | Manually saves labels on the Encord server.                                                                                                        |
| <img />  | Label Editor settings  | Settings controlling your labeling and reviewing experience.                                                                                       |
| <img />  | Open metadata          | Display any metadata for the current asset.                                                                                                        |
| <img />  | Overlay label branches | Choose which label branches to display for the current asset.                                                                                      |

***

### Quick Toolbar

<div>
  <img alt="Quick toolbar" title="Quick toolbar" />
</div>

* Display settings: adjust brightness, contrast, and gamma, or select **Show grid** to overlay a grid on images, image groups, and videos. In **Grid settings**, set the grid size in pixels, color, and opacity. Your display settings persist across sessions.
* Rotate the asset
* Pin a new [Issue](/end-to-end/Features/issues-e2e)
* Center the asset
* Zoom in and out, view the rounded zoom percentage, and click the percentage to reset the zoom to 100% or the nearest permitted zoom limit

***

### Actions

The actions bar allows your to search for and access any actions and features within the Label Editor, for both the Annotate and Review modes.

***

### Issues and Comments

<Tip>
  * Add [Issue Tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags) to a Project to flexibly categorize and group your issues.

  * Use the [Issues tab of your Project Analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues) to learn about issues in your Project.

  A complete walkthrough of all things Issues and Comments related can be found [here](/end-to-end/Features/issues-e2e).
</Tip>

Issues can be added to annotation and review tasks to communicate with other users. All issues contain comment threads relating to the entire task or specific sections of the task. A small notification badge on the *Issues* icon displays the number of unresolved issues in a task.

<div>
  <iframe />
</div>

**Types of Issues**:

* **Label rejection**: Created when a reviewer rejects labels. The reviewer is prompted to provide a reason for the rejection in the form of a comment. If all instances in a frame or image are rejected, a separate rejection issue is created for each label. Labels with rejection issues display a red Issues icon next to the instance name, which turns green once the issue is resolved.

* **File**: Apply to the entire file and can be created at any stage within the Label Editor.

* **Pinned**: Apply to a specific part of the file or frame and can be created at any stage within the Label Editor. Red *Pin*  icons indicate unresolved issues and remain red until they are marked as resolved.

* **Frame**: Apply to a specific frame and can be created at any stage within the Label Editor. Frame issues can only be created when multiple frames are present; such as in a video, image sequence, or DICOM volume.

* **Frame range**: Apply to a range of frames and can be created at any stage within the Label Editor. Frame range issues can only be created when multiple frames are present; such as in a video, image sequence, or DICOM volume. Frame range issues can only be [created during label validation](/platform-documentation/Validation/active-basics/active-comments).

* **Task requirement**: Are created for each object or classification [marked *Required* in the Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#required-attributes). The issue is resolved when the required object or classification is applied. Task requirement issues are the only issues visible in a Consensus annotate stage.

<Tip>
  - Each issue card header shows its scope. For annotation issues, the scope displays the exact label name. Selecting the card highlights the associated label; clicking a frame chip navigates to that frame and selects the corresponding issue.
  - Issue threads can be filtered by *Resolved* and *Unresolved* issues.
</Tip>

**To Create a new Issue**:

<Note>
  Issues cannot be created in a Consensus annotate stage.
</Note>

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *New issue* icon (or keyboard shortcut <kbd>Ctrl</kbd>+<kbd>N</kbd>).
3. Click the *Apply to* dropdown to select the type of issue you want to create.
4. Select any [Issue Tags](/platform-documentation/General/general-workspace-settings#issue-tags) you want to apply to the issue.
5. Add a comment to the issue.
6. If you selected 'Pin on canvas' in Step 3, click the desired location on the canvas.
7. Click **Create issue**.

<div>
  <img />
</div>

**To Resolve an Issue:**

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *tick* to mark a thread as resolved.

Resolved issues remain visible but can be filtered out. All users can resolve issues.

<div>
  <img />
</div>

**To Delete an Issue Thread:**

<Warning>
  Deleted threads are NOT counted in the [Issues analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues).
</Warning>

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *Ellipsis* icon to show more options.
3. Click **Delete thread**.

<Note>
  Users can only delete issues that they created. **Label rejections cannot be deleted, only resolved**.
</Note>

**To Reopen an Issue Thread:**

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click *Reopen* on an issue that was previously resolved.

**Use Cases**:

* **Ask questions**: Annotators and reviewers can ask questions about the task. Admins can use this feedback to improve guidance.
* **Explain task rejection**: Reviewers can provide reasons for rejection, helping annotators avoid repeating mistakes.
* **Track unresolved issues**: Keep a record of open discussions that need follow-up before finalizing annotations.

***

### Editor Lock

The 'Editor lock' is a safety feature we implemented to prevent several people making changes to the same file - annotators labeling, or reviewers reviewing the same data unit.

A warning is triggered in two cases:

1. When you have the same task open in two different tabs or browser windows:

<div>
  <img />
</div>

2. When a different user is editing the same task:

<div>
  <img />
</div>

***

## WACOM Tablet Support

Our [Label Editor](/platform-documentation/Annotate/annotate-label-editor) fully supports Wacom tablets and pens. You get the best experience if you enable [freehand drawing mode](/platform-documentation/Annotate/annotate-label-editor#freehand-drawing--polygon-coarseness).


# Label Editor - Review
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review



<Info>To ensure seamless data loading in Encord, allowlist [https://app.encord.com/](https://app.encord.com/) or [https://app.us.encord.com/](https://app.us.encord.com/) in any 3rd party VPNs, firewalls, or URL isolators. This helps to prevent potential issues with opening your data in Encord.</Info>

This documentation provides a comprehensive guide to using the Label Editor for review, covering its components, features, and the display of various elements.

## Review Mode

### Introductory Video

The following video goes through the basics of reviewing visual data in the Label Editor.

<div>
  <iframe />
</div>

### Review Mode Components

As a reviewer, your Label Editor workspace contains the following components:

* **A**. Filter and search reviews
* **B**. [Labels to review](#single-label-review)
* **C**. [Quick toolbar](#quick-toolbar)
* **D**. [Single Label Review](#single-label-review)
* **E**. [Actions](#actions)
* **F**. [Reject and Approve buttons](#reject-and-approve-buttons)
* **G**. [Editor header](#editor-header)
* **H**. [Issues](/end-to-end/Features/issues-e2e)
* **I**. [Skip Task](#skip-a-review-task) and [Edit labels](#edit-labels-during-review) buttons
* **F**. [Reject and Approve buttons](#reject-and-approve-buttons)

<Note>
  Videos, Image Sequences, Scenes, and Audio display a [timeline](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#editor-timeline) in the Label Editor.
</Note>

<div>
  <img />
</div>

<Tip>
  Use the show-hide labels buttons, workspace settings, and the drag and select in the workspace to speed up your approved label selection and review process.

  ![Optimize Review](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/projects-review-labels.gif)
</Tip>

***

### Single Label Review

The normal review mode displays all labels simultaneously, allowing you to quickly approve or reject many labels in bulk actions. Alternately, enter the *Single label review* mode by toggling the switch at the top left. The single label review mode automatically highlights the selected instance, and hides all other objects. This allows you to carefully review one instance at a time including their attributes, and quickly iterate through the different instances using the *Up* and *Down* keys on your keyboard or by clicking the appropriate buttons in the UI.

<div>
  <img />
</div>

<Note>The *Single label review* feature can also be considered "turbo review mode," analogous to the "turbo attribute mode" in annotation mode, because it allows the reviewer to quickly step through and review instance attributes. "Turbo attribute mode" in the editor settings can be disabled while in review mode.</Note>

**Single Label Review Settings**

The default zoom level for single label review can be adjusted to suit your needs.

1. Open the [editor settings](#editor-settings-menu).

2. In the *General settings* section adjust the *Set the default zoom level for single label view* value highlighted in the screenshot below. The settings will be applied for the next selected label.

<div>
  <img />
</div>

<Note>
  * Initially, the default is set to 60%
  * 20% corresponds to no zoom. It's the magnification at which the image or frame is displayed in the Label Editor.
  * To zoom in, increase the percentage value.
  * To zoom out, decrease the percentage value. The minimum value is 1%.
</Note>

***

### Skip a Review Task

In the standard and configurable Label Editors, click **Skip** when you cannot complete a review task. You can enter an optional reason, then click **Skip task**. Skipping saves your label changes and unassigns you from the task. If another review task is available, it loads in the editor; otherwise, you return to the task queue. The skip and any reason you provide are added to the task as a comment.

***

### Edit Labels During Review

It is sometimes faster, more convenient, and less error-prone to have reviewers make edits to annotations, instead of outright rejecting them. Rejection requires the return of the entire set of labels to the annotator.

*Edit review* allows reviewers to make changes to labels, remove labels, and add new labels. Approved or rejected labels cannot be edited. Only *Pending* labels can be edited by reviewers. New labels made by editors are automatically approved, and cannot be changed once they have been saved. Once all labels have been approved the task moves to the *Complete* stage.

<Tip>We recommend enabling [*Strict review*](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#strict-review) on Review blocks when configuring Workflows. *Strict review* allows reviewers to revert approved labels back to *Pending*, giving reviewers the option to make changes to new labels drawn while editing labels. </Tip>

**To edit labels in review mode:**

1. Click the **Edit labels** button.

<div>
  <img />
</div>

2. Add or remove labels, or edit existing labels as necessary using the same interface annotators use to create labels.

3. Click the **Save and return to review** button to save your edits and return to review mode.

<Note>The **Save and return to review** button replaces the **Save** and **Cancel** buttons used in earlier versions of this feature.</Note>

<div>
  <img />
</div>

<Warning>
  * There is no way to edit Classifications.
  * Labels created during *Edit review* are not added to the Review stage and can not be seen in the Label Editor.
</Warning>

***

### Pending Reviews Pane

All labels for review for a particular data asset assigned to the reviewer are automatically loaded into then *Pending reviews* pane. The labels are grouped by Ontology class.

<Tip>
  You can search for specific classes and labels by clicking the **Search** button (magnifying glass icon) in the header within both the **Pending reviews** and **Completed reviews** panes to quickly locate the items you need to review.
</Tip>

***

### Completed Reviews Pane

Completed reviews are displayed in the *Completed reviews* pane. You can click on specific objects to highlight them. Labels can be selected and then approved or rejected for a given instance or in bulk using the **Reject** and **Approve** buttons or the matching hotkeys, <kbd>b</kbd> for reject and <kbd>n</kbd> for approve. Approved labels appear in a green background and rejected labels appear in red.

<Tip>
  You can search for specific classes and labels by clicking the **Search** button (magnifying glass icon) in the header within both the **Pending reviews** and **Completed reviews** panes to quickly locate the items you need to review.
</Tip>

***

### Approve and Reject All In Frame Buttons

The **Approve all in frame** and **Reject all in frame** buttons take the named action without having to select a particular instance or set of instances. This speeds up workflows, particularly in images, where you can judge whether all instances are correct or not by looking at an individual frame.

<Warning>The **Approve all in frame** and **Reject all in frame** buttons apply to all instances present in a frame, rather than labels. This means that all instances with labels in the current frame will have all of their labels approved or rejected.</Warning>

<Tip>The **Approve all in frame** and **Reject all in frame** buttons can be hidden in the [general settings](#general-settings).</Tip>

***

### Reject and Approve Buttons

To reject/approve multiple object instances across frames, select the instances, and then click the **Reject** or **Approve** button, as appropriate. Alternately, you may press <kbd>b</kbd> for reject and <kbd>n</kbd> for approve.

***

### Review Status Color Mode

When **Label color mode (review)** is set to **By review status** in the editor settings, labels are recolored to reflect their current review state:

* **Pending** — orange
* **Approved** — green
* **Rejected** — red

Labels that you approve or reject during the current session fade to the opacity level configured by the **Reviewed label opacity** setting, making it easier to track your progress through a dense set of labels.

<Note>
  **By review status** color mode and **Reviewed label opacity** now apply to all 3D label types in point-cloud review tasks, including cuboids, spheres, polylines, and keypoints/points. This brings 3D review workflows to visual parity with 2D review.

  The opacity fade applies only to filled shapes (cuboids and spheres). Polylines and keypoints/points are recolored by review status but do not fade. For full details on 3D-specific behavior, see the [point cloud editor documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-pcd).

  This color mode is active in both standard workflow review mode and consensus review mode. It has no effect outside a review stage.
</Note>

***

### Change Review Judgement

<AccordionGroup>
  <Accordion title=" Video Tutorial - Strict review & change review judgment ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

Reviewed instances can be reverted to [*pending*](/platform-documentation/Annotate/annotate-label-editor#pending-reviews-pane). Reverting a review allows reviewers to make adjustments to one or more instances after making their initial review.

<div>
  <img />
</div>

1. Revert labels to *pending* :

* Revert an approved task to *pending* by clicking the green tick icon next to the instance.
* Revert a rejected task to *pending* by clicking the red cross icon next to the instance.

2. Once the reviewer completes their review, they need to click the **Approve task** or **Reject task** to finalize the review.

***

## Controls Common To Both Modes

### Editor Timeline

The Editor timeline visualizes when objects and instances appear throughout videos, scenes, and audio files. The cursor tracks playback in real time, always reflecting the current frame. The timeline is shown by default and can be resized or hidden by dragging it up or down.

***

### Editor Header

<div>
  <img alt="Editor header menu" title="editor header" />
</div>

The Editor header at the top-right of the navigation bar contains buttons and menu items to perform labeling activities as well as manage general app settings and notifications.

| **Icon** | **Name**               | **Description**                                                                                                                                    |
| -------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img />  | Help                   | Links to the: quick start guide, documentation, learning hub, and Encord support team.                                                             |
| <img />  | Notifications          | Shows the current status and history of actions taken in the application. This includes uploading datasets, training models, and exporting labels. |
| <img />  | Share                  | Copies the URL of the asset currently being labeled or reviewed.                                                                                   |
| <img />  | Save labels            | Manually saves labels on the Encord server.                                                                                                        |
| <img />  | Label Editor settings  | Settings controlling your labeling and reviewing experience.                                                                                       |
| <img />  | Open metadata          | Display any metadata for the current asset.                                                                                                        |
| <img />  | Overlay label branches | Choose which label branches to display for the current asset.                                                                                      |

***

### Quick Toolbar

<div>
  <img alt="Quick toolbar" title="Quick toolbar" />
</div>

* Display settings: adjust brightness, contrast, and gamma, or select **Show grid** to overlay a grid on images, image groups, and videos. In **Grid settings**, set the grid size in pixels, color, and opacity. Your display settings persist across sessions.
* Rotate the asset
* Pin a new [Issue](/end-to-end/Features/issues-e2e)
* Center the asset
* Zoom in and out, view the rounded zoom percentage, and click the percentage to reset the zoom to 100% or the nearest permitted zoom limit

***

### Actions

The actions bar allows your to search for and access any actions and features within the Label Editor, for both the Annotate and Review modes.

***

### Issues and Comments

<Tip>
  * Add [Issue Tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags) to a Project to flexibly categorize and group your issues.

  * Use the [Issues tab of your Project Analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues) to learn about issues in your Project.

  A complete walkthrough of all things Issues and Comments related can be found [here](/end-to-end/Features/issues-e2e).
</Tip>

Issues can be added to annotation and review tasks to communicate with other users. All issues contain comment threads relating to the entire task or specific sections of the task. A small notification badge on the *Issues* icon displays the number of unresolved issues in a task.

<div>
  <iframe />
</div>

**Types of Issues**:

* **Label rejection**: Created when a reviewer rejects labels. The reviewer is prompted to provide a reason for the rejection in the form of a comment. If all instances in a frame or image are rejected, a separate rejection issue is created for each label. Labels with rejection issues display a red Issues icon next to the instance name, which turns green once the issue is resolved.

* **File**: Apply to the entire file and can be created at any stage within the Label Editor.

* **Pinned**: Apply to a specific part of the file or frame and can be created at any stage within the Label Editor. Red *Pin*  icons indicate unresolved issues and remain red until they are marked as resolved.

* **Frame**: Apply to a specific frame and can be created at any stage within the Label Editor. Frame issues can only be created when multiple frames are present; such as in a video, image sequence, or DICOM volume.

* **Frame range**: Apply to a range of frames and can be created at any stage within the Label Editor. Frame range issues can only be created when multiple frames are present; such as in a video, image sequence, or DICOM volume. Frame range issues can only be [created during label validation](/platform-documentation/Validation/active-basics/active-comments).

* **Task requirement**: Are created for each object or classification [marked *Required* in the Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#required-attributes). The issue is resolved when the required object or classification is applied. Task requirement issues are the only issues visible in a Consensus annotate stage.

<Tip>
  - Each issue card header shows its scope. For annotation issues, the scope displays the exact label name. Selecting the card highlights the associated label; clicking a frame chip navigates to that frame and selects the corresponding issue.
  - Issue threads can be filtered by *Resolved* and *Unresolved* issues.
</Tip>

**To Create a new Issue**:

<Note>
  Issues cannot be created in a Consensus annotate stage.
</Note>

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *New issue* icon (or keyboard shortcut <kbd>Ctrl</kbd>+<kbd>N</kbd>).
3. Click the *Apply to* dropdown to select the type of issue you want to create.
4. Select any [Issue Tags](/platform-documentation/General/general-workspace-settings#issue-tags) you want to apply to the issue.
5. Add a comment to the issue.
6. If you selected 'Pin on canvas' in Step 3, click the desired location on the canvas.
7. Click **Create issue**.

<div>
  <img />
</div>

**To Resolve an Issue:**

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *tick* to mark a thread as resolved.

Resolved issues remain visible but can be filtered out. All users can resolve issues.

<div>
  <img />
</div>

**To Delete an Issue Thread:**

<Warning>
  Deleted threads are NOT counted in the [Issues analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues).
</Warning>

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click the *Ellipsis* icon to show more options.
3. Click **Delete thread**.

<Note>
  Users can only delete issues that they created. **Label rejections cannot be deleted, only resolved**.
</Note>

**To Reopen an Issue Thread:**

1. Open the *Issues* pane by clicking the *Issues* icon.
2. Click *Reopen* on an issue that was previously resolved.

**Use Cases**:

* **Ask questions**: Annotators and reviewers can ask questions about the task. Admins can use this feedback to improve guidance.
* **Explain task rejection**: Reviewers can provide reasons for rejection, helping annotators avoid repeating mistakes.
* **Track unresolved issues**: Keep a record of open discussions that need follow-up before finalizing annotations.

***

### Editor Lock

The 'Editor lock' is a safety feature we implemented to prevent several people making changes to the same file - annotators labeling, or reviewers reviewing the same data unit.

A warning is triggered in two cases:

1. When you have the same task open in two different tabs or browser windows:

<div>
  <img />
</div>

2. When a different user is editing the same task:

<div>
  <img />
</div>

## Caption Review Interface

For caption review tasks, Encord provides a specialized interface designed for efficient review of video captions and transcriptions. This interface includes enhanced features for streamlined caption approval and rejection workflows.

### View Chorus suggestions in Figure reviews

In Figure review stages, the caption row shows the number of Chorus suggestions that were available to the annotator. Select the caption row and press **S** to show or hide the suggestions. The suggestion used verbatim for the submitted caption is marked **chosen**. If the annotator edited a suggestion or wrote their own caption, no suggestion is marked as chosen.

Suggestions are available only when they were stored with the segment during annotation.

### Re-review resolved issues

When a task returns with resolved issues from an earlier review, affected segments display an amber ↻ badge on the timeline. On an undecided affected segment, the **Fixed since last review** notice shows prior issue details, including the rejected elements when available. When available, the affected element rows also show the previous rejection reason, issue tags, and when the issue was resolved.

Press **Tab** to move through undecided segments. Segments with resolved issues from an earlier review appear first, followed by the remaining undecided segments.

### Double-Tap Confirmation

The caption review interface uses a double-tap confirmation system to prevent accidental approvals or rejections:

<Note>All approval and rejection actions require double-tap confirmation. Press the same key or button twice to confirm your action.</Note>

**To approve a caption:**

1. Press **A** or click the **Approve** button
   The button shows "Hit A again to confirm".
2. Press **A** again or click the button again to confirm the approval

**To reject a caption:**

1. Press **R** or click the **Reject** button to open rejection options
2. Choose the rejection reason:
   * Press **1** for "Caption issue" or click the **Caption issue** button
   * Press **2** for "Video issue" or click the **Video issue** button
     The selected button shows confirmation text (for example: "Hit 1 again to confirm")
3. Press the same key again or click the button again to confirm the rejection

### Revert to pending

When reviewing tasks, you can revert approved or rejected tasks back to a pending state. This allows you to reconsider your review decision or make additional changes before finalizing the task status.

<Note>When you click the revert to pending button, it becomes disabled and shows a loading indicator while the operation is in progress. This prevents accidental multiple clicks and ensures the action completes properly.</Note>

### Auto-Play Toggle

The caption review interface includes an auto-play feature that automatically plays video content when reviewing captions:

1. Click the **Auto-play** button in the video controls to toggle auto-play on or off
   When enabled, videos automatically start playing when a caption is selected for review

<Note>
  The auto-play setting is preserved across review sessions.
</Note>

### Enhanced Video Controls

The caption review interface provides streamlined video controls:

* **Seek bar**: Click anywhere on the seek bar to jump to that position in the video
* **Speed control**: Use the dropdown or **Shift + Up/Down** arrows to adjust playback speed
* **Loop toggle**: Click the loop button or press **L** to enable/disable video looping
* **Mute toggle**: Click the mute button or press **M** to mute/unmute audio

### Keyboard Shortcuts for Caption Review

The caption review interface uses simplified keyboard shortcuts optimized for review workflows:

| Key             | Action                                           |
| --------------- | ------------------------------------------------ |
| **Space**       | Play/Pause video                                 |
| **A**           | Approve caption (press twice to confirm)         |
| **R**           | Show rejection options                           |
| **1**           | Caption issue rejection (press twice to confirm) |
| **2**           | Video issue rejection (press twice to confirm)   |
| **B**           | Back to approve/reject view                      |
| **M**           | Mute/Unmute audio                                |
| **L**           | Toggle video looping                             |
| **Shift + ↑/↓** | Adjust video playback speed                      |

<Tip>The keyboard shortcuts panel can be collapsed or expanded by clicking the chevron icon. Your preference is automatically saved for future review sessions.</Tip>

### Review Settings Persistence

The caption review interface automatically saves your preferences including:

* Playback speed settings
* Auto-play toggle state
* Video looping preference
* Audio mute state
* Keyboard shortcuts panel visibility

These settings are preserved across browser sessions and review tasks.

## Filtering Issues by Tag in the Issues Sidecar

The Issues sidecar filter panel provides two separate tag filter sections that let you precisely control which issues appear in the list.

### Including issue tags

The **Including issue tags** section shows only issues that carry at least one of the tags you select. When you select one or more tags here, the Issues sidecar hides all issues that do not match any of those tags.

<Note>This section was previously labeled **Issue tags**. The behavior is unchanged — only the label has been updated to distinguish it from the new **Excluding issue tags** section.</Note>

### Excluding issue tags

The **Excluding issue tags** section hides issues that carry any of the tags you select. When you select one or more tags here, the Issues sidecar removes any issue tagged with at least one of those tags from the list, regardless of what other tags that issue carries.

### Composing include and exclude filters

You can use both filters at the same time. When you do, an issue must satisfy both conditions to appear:

* It must carry at least one tag from **Including issue tags** (if any tags are selected there).
* It must not carry any tag from **Excluding issue tags** (if any tags are selected there).

For example, selecting **Blur** under **Including issue tags** and **Occlusion** under **Excluding issue tags** shows only issues tagged **Blur** that are not also tagged **Occlusion**.

### Mutual exclusion of tag selections

A tag you select in one filter section is automatically removed from the available options in the other section. This prevents you from selecting the same tag as both included and excluded simultaneously.

### Filter badge

The filter badge on the **Filters** button reflects selections in both the **Including issue tags** and **Excluding issue tags** sections. Clearing all filters resets both sections.

<Note>The **Excluding issue tags** filter section is only available in the main annotation editor Issues sidecar. It does not appear in other editor contexts.</Note>

***

## Label Branches

Label branches let you keep multiple versions of a Project's labels side-by-side. Use them to preserve a labeled state before a re-labeling pass, run an experiment without disturbing `main`, or hold a reviewer-only copy of labels.

<a href="https://www.loom.com/embed/795d49df662946d0b85bad2adc57ae2a" aria-label="Watch: Create & Display label branches" />

### Create Label Branches

Label branches are created in the [Label Checkpoint Workflow stage](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#branch-overlay-labels), or using the [SDK](/sdk-documentation/sdk-labels/sdk-label-versioning).

### View Label Branches

<div>
  <img />
</div>

<Note>
  This feature is only available to Workspace and Project Admins, and Team Managers in the REVIEW and COMPLETE Workflow stages.
</Note>

**To view labels from other branches:**

1. Click the **Branches** button in the Label Editor header.
   The branch overlay panel opens.

2. Select the checkboxes for the branches you want to overlay.
   Each branch displays with a unique color indicator.

3. Click outside the panel to close it.
   The selected branch labels now appear as read-only overlays in the 3D scene.

<Note>
  Branch label comparison is available in Review and Complete editor views — no feature flag or admin configuration required. Overlay labels are read-only. You cannot edit annotations from other branches directly in the overlay view.
</Note>

<Info>Audio and text-document modalities do not yet display branch names on overlay labels. The vertical fan-out uses fixed pixel offsets and is not collision-aware; in very dense scenes with many overlapping annotations, labels from multiple branches may still be difficult to read.</Info>

<Tip>For 3D Point Cloud-specific review behavior, including **Review Status Color Mode** and **Reviewed label opacity**, see the [Point Cloud Editor documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-pcd).</Tip>


# Editor Settings & Shortcuts
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts



## Editor Settings

<div>
  <img />
</div>

All users can configure the Label Editor, and configure the Label Editor to their specific needs. This includes changing the way elements display, drawing settings, and settings related to automated labeling.

<Note>A user's settings persist and do not reset at the end of a session.</Note>

Editor settings are divided into several sections which can be filtered using the search bar:

* *Data details*: Details relating to the file currently open in the Label Editor.
* [*General*](#general-settings): General interactions with the Label Editor.
* [*Label display*](#label-display-settings): Toggle elements to show or hide those elements within the Label Editor.
* [*Drawing*](#drawing-settings): Control how labels are drawn.

<Tip>Use the search bar at the top of the *Editor settings* to search for specific settings, or keywords. </Tip>

<div>
  <iframe />
</div>

### Data Details

The *Data details* section displays information about the asset currently open for annotation, or review. This information is gotten from the data itself, and is not available for direct manipulation. We use this section to provide you with valuable information about the data you are working on, including if we may have detected any possible issues with the data encoding.

| **Setting**                                                                                           | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Data title                                                                                            | The title of the file currently open in the Label Editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Data type                                                                                             | The type of data unit currently open in the Label Editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Dimensions                                                                                            | The size of the image or frame currently open in the Label Editor.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Frames per second                                                                                     | frequently abbreviated  *FPS*, this is the number of frames, or images, per second in a video. Higher FPS means smoother playback. This value is only valid for videos.                                                                                                                                                                                                                                                                                                                                          |
| [Browser compatibility](/platform-documentation/Annotate/annotate-label-editor#browser-compatibility) | Some videos may have FPS or video encoding issues synchronizing drawn labels with frames in modern browsers. You can read more about supported videos [here](/platform-documentation/General/general-supported-data#supported-file-formats), and learn more about frame synchronization issues <a href="https://blog.encord.com/post/playing-videos-is-easy-pausing-them-is-hard">here</a> and in our documentation [here](/platform-documentation/General/general-supported-data#frame-synchronization-issues). |

***

### General Settings

<img alt="general settings in label editor" title="General settings" />

The *General* section of the *Label editor settings* contains the following components:

| Feature                                                                                                            | Description                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto-save interval**                                                                                             | Controls how often labels are auto-saved (min: 15s, max: 600s, default: 120s).                                                                                                                                                     |
| **Display bulk Approve/Reject buttons**                                                                            | Toggles buttons to approve or reject all instances in a frame.                                                                                                                                                                     |
| **Invert mouse wheel zoom direction**                                                                              | Reverses the default zoom behavior for scrolling up/down.                                                                                                                                                                          |
| **Display timestamps**                                                                                             | Shows timestamps instead of frame numbers for object instances, attributes, and consensus review.                                                                                                                                  |
| **[Turbo mode](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#turbo-mode)** | Speeds up annotation by allowing rapid assignment/confirmation of attributes with auto-zooming.                                                                                                                                    |
| **Frame skip interval**                                                                                            | Sets the number of frames skipped when using frame-skip buttons.                                                                                                                                                                   |
| **Enable 'Jump to annotation' buttons in video player**                                                            | Adds controls to navigate directly between frames containing annotations.                                                                                                                                                          |
| **Enable 'Jump to classification' buttons in video player**                                                        | Adds controls to navigate directly between frames containing classifications.                                                                                                                                                      |
| **Display data title**                                                                                             | Toggles visibility of the data unit title in the Label Editor. The title appears in the top-right corner of the editor.                                                                                                            |
| **Expand classifications in classes list**                                                                         | Auto-expands all top-level classifications, making hotkeys visible for quicker annotation.                                                                                                                                         |
| **Expand all nested classifications**                                                                              | Auto-expands all nested classifications, making hotkeys visible for quicker annotation. This feature is off by default for better readability with deeply nested Ontologies. Enabling it might not work for very large Ontologies. |
| **Show next empty classification on timeline**                                                                     | Groups classifications by their base name and progressively reveals only the next unfilled one. Filled classifications remain visible. This setting is only available for Video and Data Groups projects.                          |

***

### Label Display Settings

<div>
  <img title="Label display settings" />
</div>

The *Label display* section of the *Label editor settings* contains the following components:

| Feature                            | Description                                                                                                                             |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Label color mode**               | Color labels by class or unique object                                                                                                  |
| **Label color mode (review)**      | Color labels by class, unique object, or review status during review                                                                    |
| **Display object names**           | Toggles visibility of annotation object names in the Label Editor                                                                       |
| **Display object hash**            | Toggles visibility of the label hash (ID) for annotation objects                                                                        |
| **Display object classifications** | Toggles visibility of object attributes in the Label Editor                                                                             |
| **Object label font size**         | Sets the font size (in px) for all label display settings                                                                               |
| **Blue tile outline**              | Controls the display of blue outlines around content tiles. This outline appears only for data groups, not for individual content items |

***

### Medical Imaging Settings

<Note>
  This section of the Editor settings is only visible for medical imaging (DICOM) Projects.
</Note>

The *Medical Imaging* section of the *Label editor settings* contains the following components:

| Feature                     | Description                                                                                                                                                                                                                                                                                                |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Full localizer line box** | Controls the rendering style of cross-series localizer (scout) lines. When **off** (default), Encord draws only the longest edge of the projected slice rectangle as a single clean line. When **on**, Encord draws the full projected slice outline (box or trapezoid), similar to Horos-style rendering. |

***

### Timeline Settings

The **Timeline settings** menu in Label Editors controls which labels appear on the timeline and how dynamic attributes behave. Access it from the Timeline panel in the Label Editor.

#### Dynamic Attributes

| Feature                     | Description                                                                                                                                                                                                                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Limit to a single frame** | When enabled, setting a dynamic attribute applies the value only to the current frame, not forward through the containing range.                                                                                                                                                                                               |
| **Propagate across gaps**   | When enabled, setting a dynamic attribute at the playhead propagates the value forward through all later sub-ranges of the object, not just the current contiguous segment. This setting is off by default. When **Limit to a single frame** is also enabled, it takes precedence and **Propagate across gaps** has no effect. |

<Note>**Propagate across gaps** is designed for objects that appear on disjointed frame ranges (sparse objects). When you enable this setting and set a dynamic attribute value, the value covers every later occurrence of the object automatically, stopping only at the next frame where you have explicitly set a different value for that attribute.</Note>

<Tip>For checklist attributes, each option propagates independently. Only a later explicitly set change to the same checklist option stops propagation of that option — changes to other checklist options do not affect it.</Tip>

***

### Drawing Settings

<div>
  <img alt="Drawing settings in label editor settings" title="Drawing settings" />
</div>

The *Drawing settings* section of the *Label editor settings* contains the following components:

| Feature                                    | Description                                                                                                                                                                         |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Handle size**                            | Adjusts the size of vertices and keypoints (1-10 px).                                                                                                                               |
| **Object opacity**                         | Controls label opacity (1% - 100%) for better visibility.                                                                                                                           |
| **Selected object opacity**                | Adjusts opacity multiplier (1x - 10x) for selected objects.                                                                                                                         |
| **Primitive keypoint sensitivity**         | Sets precision for selecting/moving keypoints (1.00 - 10.00).                                                                                                                       |
| **Segment anything RDP parameter**         | Sets [RDP parameter](https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm) for (SAM).                                                                      |
| **SAM3 IOU match threshold**               | Defines the minimum overlap required for SAM3 to classify multiple masks as a single tracked object.                                                                                |
| **Drawing line aides**                     | Adds crosshairs to improve label accuracy.                                                                                                                                          |
| **Freehand drawing & Polygon coarseness**  | Enables freehand drawing with adjustable coarseness.                                                                                                                                |
| **Show polyshape angles**                  | Displays angles on polygons and polylines.                                                                                                                                          |
| **Permanent drawing (new instances)**      | Allows continuous drawing of new instances without re-selecting the tool.                                                                                                           |
| **Permanent drawing (existing instances)** | Automatically moves forward and prompts labeling of the same instance on the next frame.                                                                                            |
| **Skeleton points**                        | Toggles visibility of individual [object primitive](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#object-primitives) keypoint names.        |
| **Interpolation auto adjustments**         | Keeps manually labeled frames intact while adjusting [interpolations](/platform-documentation/Annotate/automated-labeling/annotate-interpolation) with confidence scores below 99%. |
| **Ruler around cursor**                    | Displays the source pixel size, allowing you to gauge object dimensions before adding or adjusting labels.                                                                          |

***

### Object Tracking

**Number of frames to predict**

Specify how many subsequent frames that SAM 2 should continue from the current frame. For example, if you start on frame 50, and set *Number of frames to predict* to 50, the tracker attempts to predict labels on frames up to and including frame 100.

**Advanced tracking**

This toggle enables the advanced SAM 2 tracking algorithm, which improves accuracy but runs at a slower speed. It is enabled by default.

***

### Scene

<Note>
  This section of the Editor settings is specific to PCD Projects and does not appear for other modalities.
</Note>

<Note>Scene settings now persist across sessions. Your preferences for point cloud size, opacity, and helper visibility are automatically saved and restored when you reload the annotation editor.</Note>

<AccordionGroup>
  <Accordion title="General settings">
    **Input Device**

    Specify using a `mouse` or `trackpad` to rotate or pan in the workspace.

    <Tip>
      We **STRONGLY** recommend using a mouse to rotate or pan in the workspace.
    </Tip>

    **Pre-load data**

    Pre-load data in the background for smoother navigation. Enabling this setting can improve performance when annotating or reviewing point cloud data.

    ***
  </Accordion>

  <Accordion title="Cuboid settings">
    **Face**

    Shows/Hides the "face" of cuboids in the PCD workspace.

    **Orientation**

    Shows/Hides the orientation of cuboids in the PCD workspace.

    **Set front face from motion**

    When enabled, Encord automatically orients the front face of a cuboid annotation based on the object's local direction of motion whenever you add or paste a keyframe. It ignores small movements caused by annotation jitter. Encord re-orients existing keyframes for that cuboid in the same operation, except for frames where you manually set the front face during the current editor session, so undoing the action also reverts the orientation change.

    <Note>
      This setting is disabled by default. When disabled, the front face follows how the cuboid was originally created. You can always set the front face manually at any time using `Alt+Click`.
    </Note>

    <Tip>
      Use **Set front face from motion** when annotating moving objects (such as vehicles or pedestrians) to keep cuboid orientations consistent with the direction of travel across all keyframes.
    </Tip>

    **Setting the front face manually with Alt+Click**

    Hold `Alt` and click any face of a cuboid to designate that face as the front face on the clicked frame. The frame becomes a keyframe, and automatic orientation from motion does not override your selection during the current editor session. After you reopen the editor, a later automatic trajectory update may change that frame. Hold `Alt+Shift` and click a face to set the front face across every frame instead. These shortcuts work whether the cuboid is selected or unselected.

    While you hold `Alt`, Encord hides the cuboid's drag-handle controls and makes the cuboid body the click target, so you can accurately pick the intended face without accidentally resizing the cuboid.

    When you set the front face across every frame, keyframes update their stored rotation, and interpolated frames rotate to match but retain their interpolated status.

    **Show Cuboid Trajectories**

    When enabled, Encord renders the selected cuboid's full trajectory path across frames. The trajectory path appears in the main 3D view and in the top-down (bird's-eye) tile of grid view, giving you a visual reference line for the object's direction of travel. The trajectory does not appear in front, back, left, right, or camera-view tiles — only the top-down tile shows it, because the path collapses to a point or line from those angles.

    <Tip>
      Use the trajectory path in the top-down grid view tile to verify and correct cuboid orientation against the object's actual direction of travel, especially when a vehicle or object has an incorrect heading across keyframes. You can do this without leaving grid view.
    </Tip>

    <Note>
      The trajectory overlay in the top-down grid tile requires **Show Cuboid Trajectories** to be enabled. Cuboids with only a single frame of annotation have no trajectory data and display nothing.
    </Note>
  </Accordion>

  <Accordion title="Helpers">
    **Ground**

    Shows/Hides the "ground" plane as a grid in the PCD workspace.

    **Axis**

    Shows/Hides the axis of the point of origin in the PCD workspace.

    **Cameras**

    Shows/Hides camera helper lines to aid in annotating PCD.

    **Background**

    Shows/Hides the background in the PCD workspace.
  </Accordion>

  <Accordion title="Color filter">
    Click **Filters** in the 3D Label Editor Toolbar, then expand **Color**. The section reports when the loaded point cloud has no color or intensity data.

    <Note>
      The color filter applies globally to all loaded point clouds in the scene. When you enable the filter, points outside the selected range are hidden in the viewport and cannot be selected by any segmentation tool.
    </Note>

    **Filter modes**

    Select a mode using the mode selector at the top of the section:

    * **RGB** — Filter points by red, green, and blue channel ranges (0–255 per channel). Available when the point cloud contains file color data.
    * **HSV** — Filter points by hue, saturation, and value ranges. Available when the point cloud contains file color data.
    * **Intensity** — Filter points by intensity range (0–100%). Available when the point cloud contains intensity data.

    Use the range sliders to set the minimum and maximum values for each channel. Only points whose color or intensity falls within all specified ranges remain visible.

    **Eyedropper (Pick color from scene)**

    Click **Pick color from scene** in the **Color** section of the **Filters** pane to activate the eyedropper. Then click any point in the 3D viewport to seed the filter with that point's color or intensity. The sliders update automatically to a range centered on the sampled value.

    **Composition with other filters**

    The color filter works together with the height filter and slicer planes. A point must pass all active filters to remain visible and selectable.

    **Segmentation tool integration**

    When the color filter is active, the lasso, brush, and cuboid segmentation tools automatically exclude filtered-out points from selection. Only visible points can be selected.

    <Note>
      If the cuboid tool cannot resolve a point cloud in the rendered scene, it falls back to unfiltered selection for that cloud.
    </Note>
  </Accordion>

  <Accordion title="Mesh asset settings">
    When a Scene contains mesh assets, use the Scene settings to inspect their geometry and appearance:

    * Use the switch for each mesh stream to show or hide that part of the asset.
    * Set **Mesh appearance** to **Textured** to display the asset's colors, or **Untextured** to apply a neutral fill that makes its shape easier to inspect.
    * With **Untextured** selected, enable **Faceted shading** to shade each triangle separately instead of smoothing the surface.
    * Adjust **Key light** to control directional shading and **Ambient light** to control the even fill light. These lighting preferences persist across sessions.

    Rest the pointer over a visible mesh to display its stream name and highlight that part.

    <Note>
      These settings appear only when the Scene contains a mesh asset. They do not affect point-cloud-only Scenes.
    </Note>
  </Accordion>

  <Accordion title="Point cloud settings">
    <Note>
      A Scene can optionally include view settings which will be applied when opening it, such as the point cloud size and coloring mode. See [Scene view settings](/sdk-documentation/index-sdk/sdk-scenes#scene-view-settings) to learn more.
    </Note>

    **Color settings**

    You can change the color of point cloud data in the PCD workspace. Here are the options:

    * **Solid**: Displays points with a single uniform color.
    * **Height**: Displays points in colors based on the distance from the "ground" plane.
      <Note>
        You can adjust the "ground" plane using the [ground height]() feature on the Editor toolbar.
      </Note>
    * **Provided**: Displays points in colors based on how they were originally captured and recorded. Available when a point cloud includes color data.
    * **Image**: Displays points in colors by projecting camera image data onto the points. Available when the scene includes cameras.
    * **Sensor**: Displays points colored by the sensor that captured them, making it easy to visually identify which sensor contributed which points in a multi-sensor setup. Available when the scene includes multiple point cloud streams.

    The settings panel does not show color modes that the scene data does not support. If a saved color mode is unsupported in a scene, the point cloud renders using **Solid**.

    The **Display point intensity** setting appears only when a point cloud in the Scene includes intensity data. The **sRGB color correction** setting appears only when the Scene includes provided point-cloud colors.

    <Note>
      * When you enable **Color by sensor** mode, points from different sensors are automatically assigned distinct colors from a fixed palette of 20 maximally distinct colors.

      * Sensor colors are assigned consistently based on the sensor's stream ID, so the same sensor is always use the same color across different frames and sessions.
    </Note>

    **PCD display settings**

    You can change the display settings of point cloud data in the PCD workspace. Here are the options:

    * Show: Displays point cloud data in the PCD workspace.
    * Merge: Displays all point cloud data across time in the PCD workspace.
    * Uniform size: Displays all point cloud data in a uniform size in the PCD workspace.
    * Hide segmented: Hides all point cloud data that is behind segmented objects in the PCD workspace.
      <Note>
        Only segmented objects that are set to be hidden hide all point cloud data behind them.
      </Note>
    * Hide Unsegmented: Hides all points not covered by any segmentation label. This toggle is off by default. You can also toggle this setting using `Shift`+`U`.

      <Note>
        When you enable **Hide Unsegmented** before creating any segmentations, no points are hidden because no segmentation coverage exists yet.
      </Note>

      <Note>
        You can combine **Hide Unsegmented** with **Hide segmented** to show only points that belong to visible segmentation labels.
      </Note>

      <Tip>
        Use **Hide Unsegmented** when trimming or refining segmentations on large point cloud scenes — hiding background points reduces visual clutter and prevents the brush and lasso tools from accidentally selecting unlabeled points.
      </Tip>
  </Accordion>

  <Accordion title="Point cloud size">
    Specify the size of cloud data points in the PCD workspace.
  </Accordion>

  <Accordion title="Point cloud opacity in 2D views">
    Specifies the opacity of PCD in 2D views.

    <Note>
      The default value is 0. PCD does not display in 2D views with a value of 0.
    </Note>
  </Accordion>

  <Accordion title="Render full camera image">
    Renders the full image captured by the camera beyond the source image's nominal bounds. Enable this setting when working with wide-angle or fisheye lenses in 3D scenes to display the complete captured area in the rectified camera view.

    <Note>
      This setting is off by default. When disabled, the rectified camera view clips to the source image's nominal bounds. This setting is only visible when you are working in a 3D scene context.
    </Note>

    <Tip>
      Enable **Render full camera image** when your camera tiles appear cropped. You can also search for this setting in the settings panel using keywords such as "fisheye", "wide-angle", "distortion", "rectified", or "clip".
    </Tip>
  </Accordion>

  <Accordion title="Ground mesh fitting">
    The ground mesh fitting tool improves ground detection in LiDAR/point cloud scenes, including curved roads and uneven terrain. Encord automatically detects and fits the mesh in the background as the scene loads. You can then activate it as an overlay in the 3D viewer, giving you a visual reference for scene geometry and making it easier to focus on objects of interest.

    **Ground segmentation**

    Encord automatically segments the point cloud into ground and non-ground points as the scene loads. Click **Adjust ground** in the toolbar, then **Use ground mesh** when the detected mesh is ready. To switch back without discarding the detected mesh, click **Use ground plane**. The segmentation algorithm handles curved and uneven terrain more accurately than a flat ground plane.

    **Height filter integration**

    When you fit a ground mesh, the **Height** section of the **Filters** panel gains a **Ground mesh** mode. In this mode, the height filter measures each point's height above the local mesh surface rather than a flat plane, enabling accurate filtering over curved or uneven terrain such as cambered roads or hilly ground.

    To use the height filter with a fitted ground mesh:

    1. Click **Adjust ground** in the toolbar, then click **Use ground mesh** when the detected mesh is ready.
    2. Close the **Adjust ground** pane.
    3. Click **Filters** in the toolbar, then expand **Height**.
    4. Select **Ground mesh** from the mode selector. The selector shows **Ground mesh** when a fitted mesh is active, or **Ground plane** when only a flat ground plane is available.
    5. Adjust the **Min** and **Max** bounds. The histogram and range reflect heights above the mesh surface.

    <Note>
      The **Ground mesh** option appears in the height filter mode selector only when a fitted ground mesh is active. If no ground mesh has been fitted, the selector shows **Ground plane** instead.
    </Note>

    Click **Remove ground** to set the minimum height from the fitted mesh's detected ground level and hide points identified as ground.

    Lasso (freehand) and brush segmentation tools respect the ground-mesh-relative height filter when **Ground mesh** mode is active, so only points above the mesh surface at the specified height range are included in your selection.

    To open or close the **Filters** panel, press `F`. Use the reset button beside **Height** to clear the height filter.

    When you select a cuboid and click **Level**, Encord aligns the cuboid with the local slope of the active ground mesh. If you use the ground plane instead, **Level** aligns the cuboid with that plane. The action preserves the cuboid's position, size, and heading.

    <Note>
      Cuboid fitting on the ground plane currently uses the flat ground plane, not the terrain mesh. Full integration with the terrain mesh is planned for a future release.
    </Note>

    <Note>
      Ground mesh fitting runs in the browser. On large or merged point clouds, the fitting process may temporarily affect UI responsiveness while it completes.
    </Note>
  </Accordion>

  <Accordion title="Faded point opacity">
    Specifies the opacity of data points that fade into the background. For example, all data points outside of a Scene slice.
  </Accordion>

  <Accordion title="Color points inside cuboids">
    Controls whether points that fall inside cuboids are highlighted with special coloring to make them more visible. This setting overrides the normal point coloring mode for points contained within cuboid annotations.

    | Option            | Description                                                          |
    | ----------------- | -------------------------------------------------------------------- |
    | **All cuboids**   | Highlights points inside every cuboid annotation (default behavior). |
    | **Selected only** | Only highlights points inside the currently selected cuboid.         |
    | **None**          | Disables cuboid point highlighting entirely.                         |

    <Tip>Use "Selected only" mode when working with many overlapping cuboids to focus on the cuboid you're currently editing.</Tip>
  </Accordion>

  <Accordion title="Label color mode (review)">
    Controls how 3D labels are colored during workflow review and consensus review tasks. This setting applies to all 3D label types: cuboids, spheres, polylines, and keypoints/points.

    <Note>
      This setting only takes effect when you are in a workflow review stage or consensus review stage. It has no effect outside of review tasks.
    </Note>

    **By review status**

    When you set **Label color mode (review)** to **By review status**, all 3D labels in the point cloud viewport are recolored according to their current review state:

    | Review state | Color  |
    | ------------ | ------ |
    | Pending      | Orange |
    | Approved     | Green  |
    | Rejected     | Red    |

    Labels you action (approve or reject) during the current review session fade to the opacity configured in **Reviewed label opacity**, reducing visual clutter as you work through the scene.

    <Note>
      The opacity fade applies only to filled shapes — cuboids and spheres. Polylines and keypoints/points are recolored by review status but do not fade.
    </Note>

    Selected 3D labels retain their review-status fill color when selected. Only the selection outline switches to the selection highlight color, matching the behavior in 2D review tasks.
  </Accordion>

  <Accordion title="Reviewed label opacity">
    Specifies the opacity applied to 3D labels that you have actioned (approved or rejected) during the current review session. Reducing this value fades reviewed labels into the background, making it easier to focus on labels that still require review.

    <Note>
      The opacity fade applies only to filled shapes — cuboids and spheres. Polylines and keypoints/points are recolored by review status but are not affected by this opacity setting.
    </Note>

    <Note>
      This setting only takes effect when **Label color mode (review)** is set to **By review status** and you are in a workflow review stage or consensus review stage.
    </Note>
  </Accordion>

  <Accordion title="In-editor tutorials (Scene projects)">
    Scene-type (3D LiDAR/point-cloud) projects include interactive in-editor tutorials you can access directly from the label editor. Each tutorial guides you through a specific workflow step by step, and the editor automatically detects when you complete each action so the tutorial advances in real time.

    **Accessing tutorials**

    Click the **Help** button in the top toolbar, then select **Tutorials**. The tutorials panel lists all available tutorials for your project type. Click **Start** on any tutorial card to begin.

    **Cuboids across time**

    The **Cuboids across time** tutorial teaches you the full multi-frame cuboid tracking workflow. It takes approximately 5 minutes and covers the following steps:

    1. **Select a cuboid** — select an existing cuboid in the 3D view.
    2. **Copy the cuboid** — copy the selected cuboid to the clipboard.
    3. **Place it on a later frame** — navigate forward several frames, then hold `Shift` to preview the copied cuboid and click to place it.
    4. **Interpolate between keyframes** — fill every frame between your two keyframes using the interpolate shortcut or the right-click menu.
    5. **View the trajectory** — review the trajectory the editor draws between keyframes, then confirm with **OK**.
    6. **Turn on auto re-interpolation** — enable **Auto interpolate** under **Drawing** in the editor settings so the editor automatically re-runs interpolation when you adjust a keyframe.
    7. **Edit the trajectory in grid view** — open grid view, drag the cuboid in any frame column to refine its position, and close grid view when done.
    8. **Set the front face** — use `Alt`+click to set the front face on the current frame, or add `Shift` to set it on every frame.
    9. **Toggle a keyframe** — use `Alt`+`K` to unmark or re-mark the current frame as a keyframe.
    10. **Lock the size** — click **Lock size** in the cuboid pane to enforce a uniform size across all frames.
    11. **Make it static** — use `Alt`+`S` or the pushpin in the cuboid pane to mark the object as static, copying its current pose to every frame.

    After you complete a step, the tutorial advances automatically. Step 5 (View the trajectory) requires you to click **OK** to advance manually. Once you finish a step, you can click its title to re-expand it and re-read the instructions at any time.

    <Note>
      The **Cuboids across time** tutorial is only available in Scene-type (3D LiDAR/point-cloud) projects. It does not appear for other project types.
    </Note>
  </Accordion>
</AccordionGroup>

***

## Metadata Panel

The metadata panel displays item metadata for the currently open data unit in the Label Editor. Access the metadata panel using the **Metadata** button (code icon) in the editor header.

<Info> This feature can be enabled or disabled per account. Admins may wish to disable it if task metadata contains sensitive information that should not be visible to Taskers. </Info>

<Note>The metadata panel only appears when metadata is available for the current data unit</Note>

<div>
  <img alt="Metadata panel" title="Metadata panel" />
</div>

**Metadata panel features**:

The metadata panel provides the following capabilities:

* **Field-by-field display**: Each metadata field appears with its key and value clearly separated
* **Copy functionality**: Click any field to copy its value to your clipboard, or use the copy button in the header to copy all metadata as JSON
* **URL detection**: URLs in metadata values automatically become clickable links
* **JSON formatting**: Complex nested objects display as formatted JSON for better readability
* **Large metadata handling**: Very large metadata files show a message directing you to use the copy function
* **Embedding field filtering**: Fields containing "embedding" in their names are automatically hidden from display to improve readability. Hidden fields are listed in a "Hidden fields" section at the bottom of the panel.

<Tip>Use the copy button in the metadata panel header to copy all metadata as formatted JSON for use in external tools.</Tip>

<Note>Embedding-related metadata fields are automatically filtered out of the display but remain accessible through the copy function. The panel shows which fields were hidden in a "Hidden fields" section.</Note>

***

## Trackpad Support

Encord's Label Editor supports trackpad gestures for improved navigation and annotation workflows. This feature works alongside traditional mouse controls to provide a more intuitive experience when using laptops or external trackpads.

### Trackpad Gestures

The Label Editor recognizes the following trackpad gestures:

* **Pinch-to-zoom**: Use two fingers to pinch in or out for precise zoom control. Pinch out (fingers apart) to zoom in, pinch in (fingers together) to zoom out.
* **Two-finger scroll**: Use two fingers to pan around the canvas. The content follows your finger movement naturally.

<Note>Trackpad support is automatically enabled when you set your input device to "trackpad" in the Scene settings. For non-scene projects, trackpad gestures work automatically when detected by your browser.</Note>

### Input Device Configuration

For point cloud data (PCD) Projects, you can specify your preferred input device in the Scene settings:

1. Open the **Editor settings** panel
2. Navigate to the **Scene** section
3. Under **General settings**, select your **Input Device**:
   * **Mouse**: Optimized for traditional mouse interactions
   * **Trackpad**: Enables trackpad gesture recognition and optimized sensitivity

<Tip>We strongly recommend using a mouse for point cloud annotation, but trackpad support is available for users who prefer or require trackpad navigation.</Tip>

### Gesture Behavior

**Zoom behavior**:

* Trackpad pinch-zoom provides smooth, proportional zooming based on your gesture speed
* Zoom centers on your cursor position for precise control
* The **Invert mouse wheel zoom direction** setting also affects trackpad pinch direction

**Pan behavior**:

* Two-finger scroll moves the content in the direction of your fingers
* Panning disables auto-centering, preserving your chosen view across frame changes
* Pan sensitivity is optimized for trackpad input

<Info>When using trackpad mode, two-finger scroll is dedicated to panning. Frame navigation using scroll gestures is disabled to prevent conflicts with pan gestures.</Info>

***

## Keyboard Shortcuts

<Tip>
  Encord supports customizing keyboard shortcuts to suit your needs. Contact us at [support@encord.com](mailto:support@encord.com) for more information.
</Tip>

<Note>The words 'keyboard shortcuts' and 'hotkeys' are used interchangeably and refer to the same concept. </Note>

<Tip>A full list of keyboard shortcuts can be found in the Label Editor. Use <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd> K </kbd> to open the full list of shortcuts. </Tip>

<Note>Windows and Mac may have different keyboard shortcuts. Use <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd> K </kbd> to open the full list of shortcuts</Note>

Use the following hotkeys to speed up common or useful operations.

### Actions Menu

The Actions menu provides quick access to all available Label Editor functions through a searchable interface. Access it using <kbd>Ctrl</kbd> + <kbd>K</kbd> (Windows) or <kbd>Cmd</kbd> + <kbd>K</kbd> (Mac).

The Actions menu includes:

* All keyboard shortcuts with their hotkey combinations
* Editor settings and configuration options
* Navigation and tool selection commands
* Automated labeling functions
* All Ontology classes for annotation creation, including those without assigned hotkeys

<Tip>Use the search bar in the actions menu to quickly find specific functions by typing keywords or partial command names.</Tip>

<Note>In large Ontologies where not all classes have assigned hotkeys, the Actions menu displays all available annotation classes, making it easy to create labels for any object type in your Ontology.</Note>

<Note>Some actions — such as **Go to middle frame** — have no default keyboard shortcut assigned. These actions still appear in the Actions menu and are fully functional. You can assign a custom shortcut to any unassigned action via the hotkey customization settings. Contact [support@encord.com](mailto:support@encord.com) to enable hotkey customization for your account.</Note>

### Review Mode

| Action                               | Shortcut                                      | Configurable? |
| ------------------------------------ | --------------------------------------------- | ------------- |
| Approve selected label               | <kbd>N</kbd>                                  | Yes           |
| Reject selected label                | <kbd>B</kbd>                                  | Yes           |
| Approve all labels                   | No default hotkey. Must be configured.        | Yes           |
| Reject all labels                    | No default hotkey. Must be configured.        | Yes           |
| Toggle review edit mode              | <kbd>Ctrl</kbd> + <kbd>E</kbd>                | No            |
| Turbo attribute mode                 | <kbd>Ctrl</kbd> + <kbd>⇧</kbd> + <kbd>T</kbd> | No            |
| Toggle auto zoom (Turbo review mode) | <kbd>Ctrl</kbd> + <kbd>⇧</kbd> + <kbd>Y</kbd> | No            |
| Review mode                          | <kbd>Ctrl</kbd> + <kbd>⇧</kbd> + <kbd>R</kbd> | No            |

**Single label review:**

<Info>
  Single label review can be enabled using the hotkey <kbd>CTRL</kbd>+<kbd>SHIFT</kbd>+<kbd>T</kbd>
</Info>

| **Action**           | **Hotkey**   | **Configurable?** |
| -------------------- | ------------ | ----------------- |
| Go to next label     | <kbd>↑</kbd> | Yes               |
| Go to previous label | <kbd>↓</kbd> | Yes               |
| Previous             | <kbd>↓</kbd> | No                |
| Next                 | <kbd>↑</kbd> | No                |

| **Action**                      | **Windows**                                                        | **Mac**                                           | **Description**                                                           |
| ------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------- |
| Toggle single label review mode | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>T</kbd> | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>T</kbd> | Enables single label review mode for focused review of individual labels. |

***

### General

| Action                                        | Shortcut                                                           |
| --------------------------------------------- | ------------------------------------------------------------------ |
| Save                                          | <kbd>Ctrl + S</kbd>                                                |
| Submit task                                   | <kbd>⇧ + Enter</kbd>                                               |
| Shortcuts menu                                | <kbd>Ctrl + ⇧ + K</kbd>                                            |
| Next                                          | <kbd>↑</kbd>                                                       |
| Previous                                      | <kbd>↓</kbd>                                                       |
| Approve                                       | <kbd>N</kbd>                                                       |
| Reject                                        | <kbd>B</kbd>                                                       |
| Next frame                                    | <kbd>→</kbd>                                                       |
| Previous frame                                | <kbd>←</kbd>                                                       |
| Play / Pause                                  | <kbd>Space</kbd>                                                   |
| Copy (Mac)                                    | <kbd>⌘ + C</kbd>                                                   |
| Copy (Windows)                                | <kbd>Ctrl + C</kbd>                                                |
| Paste (Mac)                                   | <kbd>⌘ + V</kbd>                                                   |
| Paste (Windows)                               | <kbd>Ctrl + V</kbd>                                                |
| Special paste (Mac)                           | <kbd>⌘ + ⇧ + V</kbd>                                               |
| Special paste (Windows)                       | <kbd>Ctrl + ⇧ + V</kbd>                                            |
| Delete                                        | <kbd>Backspace</kbd>                                               |
| Delete selected object from frame             | <kbd>⇧ + D</kbd>                                                   |
| Select all (Mac)                              | <kbd>Ctrl + A</kbd>                                                |
| Select all (Windows)                          | <kbd>Alt + Ctrl + A</kbd>                                          |
| Complete                                      | <kbd>Enter</kbd>                                                   |
| Cancel                                        | <kbd>Esc</kbd>                                                     |
| Change class type                             | <kbd>C</kbd>                                                       |
| Track selected object from frame              | <kbd>⇧ + T</kbd>                                                   |
| Interpolate selected object from frame        | <kbd>⇧ + I</kbd>                                                   |
| Undo (Mac)                                    | <kbd>⌘ + Z</kbd>                                                   |
| Undo (Windows)                                | <kbd>Ctrl + Z</kbd>                                                |
| Redo (Mac)                                    | <kbd>⌘ + ⇧ + Z</kbd>                                               |
| Redo (Windows)                                | <kbd>Ctrl + ⇧ + Z</kbd>                                            |
| Drag image (Windows)                          | <kbd>Ctrl</kbd> + Click and drag                                   |
| Drag image (Mac)                              | <kbd>⌘ </kbd> + Click and drag                                     |
| Toggle visibility (all labels)                | <kbd>Shift</kbd> + <kbd>H</kbd>                                    |
| Hide all labels, including selected (Mac)     | <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>H</kbd>               |
| Hide all labels, including selected (Windows) | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>H</kbd>                  |
| Display object name in label title            | <kbd>Shift</kbd> + <kbd>N</kbd>                                    |
| Switch Tile (Data Groups & DICOM)             | <kbd>Option</kbd> + <kbd>S</kbd>                                   |
| Rotate active tile 90°                        | <kbd>Alt</kbd>/<kbd>Option</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd> |
| Rotate all tiles 90°                          | No default shortcut. Available from the Actions menu.              |

**Keyframes:**

| Action            | Shortcut         |
| ----------------- | ---------------- |
| Add keyframe      | <kbd>⇧ + A</kbd> |
| Delete keyframe   | <kbd>⇧ + D</kbd> |
| Previous keyframe | <kbd>⇧ + ←</kbd> |
| Next keyframe     | <kbd>⇧ + →</kbd> |

<Note>These keyframe shortcuts belong to the legacy dynamic-attribute keyframe workflow and are not available in the current timeline. Dynamic attributes are now edited as frame ranges (blocks). See [Dynamic attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes) for the current workflow.</Note>

***

### Annotate Mode

**Common Actions:**

| Action                                                                               | Shortcut                                            |
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| Permanent drawing                                                                    | <kbd>Ctrl + ⇧ + P</kbd>                             |
| Freehand drawing                                                                     | <kbd>D</kbd>                                        |
| [SAM](/platform-documentation/Annotate/automated-labeling/annotate-sam) segmentation | *Ontology hotkey* + <kbd>Shift</kbd> + <kbd>A</kbd> |
| Pan                                                                                  | Middle Mouse Button                                 |
| Go to middle frame                                                                   | None (assignable)                                   |

<Note>**Go to middle frame** has no default keyboard shortcut. You can assign one via the hotkey customization settings in the label editor.</Note>

**Classification Ranges:**

| Action                   | Shortcut     |
| ------------------------ | ------------ |
| Add range                | <kbd>N</kbd> |
| Save range               | <kbd>M</kbd> |
| Set to this frame        | <kbd>X</kbd> |
| Set to this frame & save | <kbd>Z</kbd> |
| Set start to this frame  | <kbd>C</kbd> |
| Set end to this frame    | <kbd>V</kbd> |

**Draw Polygon Mode:**

| Action              | Shortcut         |
| ------------------- | ---------------- |
| Cancel              | <kbd>Esc</kbd>   |
| Complete            | <kbd>Enter</kbd> |
| Select brush tool   | <kbd>G</kbd>     |
| Select eraser       | <kbd>H</kbd>     |
| Increase brush size | <kbd>\[</kbd>    |
| Decrease brush size | <kbd>]</kbd>     |
| Add vertex          | <kbd>A</kbd>     |
| Remove vertex       | <kbd>S</kbd>     |
| Edit vertex         | <kbd>F</kbd>     |
| Brush tool          | <kbd>G</kbd>     |

**Draw Bitmask Mode:**

| Action                                                | Shortcut         |
| ----------------------------------------------------- | ---------------- |
| Cancel                                                | <kbd>Esc</kbd>   |
| Complete                                              | <kbd>Enter</kbd> |
| Select brush                                          | <kbd>F</kbd>     |
| Increase brush size                                   | <kbd>]</kbd>     |
| Decrease brush size                                   | <kbd>\[</kbd>    |
| Select eraser                                         | <kbd>H</kbd>     |
| Select polygon tool                                   | <kbd>G</kbd>     |
| Toggle threshold mode                                 | <kbd>J</kbd>     |
| Select eye-drop tool (Once thresholding is turned on) | <kbd>K</kbd>     |

***DICOM specific operations:***

| **Action**             | **Hotkey**                                                                  |
| ---------------------- | --------------------------------------------------------------------------- |
| Windowing modification | <kbd>Alt</kbd> + <kbd>W</kbd> / <kbd> Option </kbd>  +  <kbd>W </kbd>       |
| Measurement tool       | <kbd> Alt </kbd>  +  <kbd> M </kbd> / <kbd> Option </kbd>  +  <kbd>M </kbd> |

**Bulk 3D Scene Editor Copy/Paste keyboard shortcuts**

| Action                            | Windows                                        | Mac                                               |
| --------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
| Select all cuboids                | <kbd>Ctrl + A</kbd>                            | <kbd>Command + A</kbd>                            |
| Copy selected cuboids             | <kbd>Ctrl + C</kbd>                            | <kbd>Command + C</kbd>                            |
| Place copied group                | <kbd>Shift + Click</kbd>                       | <kbd>Shift + Click</kbd>                          |
| Yaw-rotate group before placement | <kbd>R</kbd>                                   | <kbd>R</kbd>                                      |
| Undo bulk paste                   | <kbd>Ctrl + Z</kbd>                            | <kbd>Command + Z</kbd>                            |
| Clear clipboard                   | <kbd>Ctrl + Shift + C</kbd> (nothing selected) | <kbd>Command + Shift + C</kbd> (nothing selected) |

## Label Editor Settings Templates

Workspace and Project Admins can configure Label Editor templates to provide a consistent and optimized experience for their annotators and reviewers on a Project.

Annotators and reviewers can make the choice of using the Label Editor settings or customizing the Label Editor settings.

### Configure Label Editor Settings templates

Only Workspace and Project Admins can create Label Editor templates.

![Create Label Editor Settings Template](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-editor-settings-template-create.gif)

**To create a Label Editor Settings Template:**

1. Go to **Annotate > Projects > \[select a Project]**.
   The *Project* page appears.

2. Click **Queue**.
   The *Task Queue* appears.

3. Click **Initiate** for a data unit in the queue.

4. Click the **Editor settings** icon.
   The *Editor settings* panel appears.

5. Click **Use Project settings**.
   The *Use Project settings* panel appears.

6. Specify the Label Editor settings you want your annotators and reviewers to use in the Project.

7. Click **Select a template**.

8. Click **Save current settings as template**.
   A dialog box appears.

9. Provide a meaningful name and description for the template.

10. Click **Set as template** to use the template in the current Project.

11. Click **Save**.

### Apply a Label Editor Settings Template

Only Workspace and Project Admins can apply Label Editor templates to Projects.

[Apply Label Editor Settings Template](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-editor-settings-template-select.gif)

**To apply a Label Editor Settings Template to a Project:**

1. Go to **Annotate > Projects > \[select a Project]**.
   The *Project* page appears.

2. Click **Queue**.
   The *Task Queue* appears.

3. Click **Initiate** for a data unit in the queue.

4. Click the **Editor settings** icon.
   The *Editor settings* panel appears.

5. Click **Use Project settings**.
   The *Use Project settings* panel appears.

6. Click **Select a template**.

7. Select the template you want to use.

### Use Your Own Label Editor Settings

Annotators and reviewers can use their own settings instead of the Label Editor Setting template settings.

![Use your own settings](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-editor-settings-template-use-own-settings.gif)

**To use your own settings instead of the Label Editor Template settings:**

1. Go to **Annotate > Projects > \[select a Project]**.
   The *Project* page appears.

2. Click **Queue**.
   The *Task Queue* appears.

3. Click **Initiate** for a data unit in the queue.

4. Click the **Editor settings** icon.
   The *Editor settings* panel appears.

5. Click **Use my user settings**.


# Mammography
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-mammo



Encord provides native support for Mammography. After uploading your files to the Encord platform, Mammography studies are automatically detected and optimized for a smooth annotation experience. This means you can view and edit multiple series at once, and navigate on a study-level.

We use the following metadata tags to detect mammography scans:

* [Modality](https://dicom.innolitics.com/ciods/encapsulated-cda/encapsulated-document-series/00080060)
* [Laterality](https://dicom.innolitics.com/ciods/ct-image/general-series/00200060) or [image laterality](https://dicom.innolitics.com/ciods/segmentation/general-image/00200062)
* [View position](https://dicom.innolitics.com/ciods/digital-x-ray-image/dx-positioning/00185101)

<Tip>We recommend rendering mammography files in their native resolution in the Label Editor. The native resolution setting can be found in the [DICOM editor settings](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#dicom-editor-settings).</Tip>

<Note>This page documents features and optimizations specific to mammography workflows. For working with other DICOM modalities, please check the general DICOM guide [here](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom) </Note>

## Annotating in different views

You can switch the slice that is being annotated in a hanging protocol by switching out the tile being annotated, or by changing which tile can be annotated.

<Tip>The tile currently being annotated is indicated by a purple toolbar</Tip>

**To select a tile for annotation**

* Click the *Switch tiles* icon highlighted in the image below.
* Click the three dots icon highlighted in the image below and select **Annotate from this file**.

**To move a tile to the one currently being annotated**

1. Click the three dots icon highlighted in the image below
2. Select **Annotate and swap tiles**.

<div>
  <img />
</div>

***

## Expand tile

You can expand the tile currently being annotated for a better view of the anatomical features, and more precise labels.

How to expand the tile currently being annotated depends on the tile layout currently being used.

* Click the *Expand tile* icon on the tile currently being annotated to expand the tile.
* If the *Expand tile* icon is not visible above the tile currently being annotated, click the three dots icon and select **Expand tile**.

<Tip>To return to your [default tile layout](#default-layouts) click the *Reset layout to default* icon. </Tip>

***

## Hanging protocols

<Note>
  Hanging protocols only apply to the current task. Learn how to set the editor layout for the entire Project [here](/platform-documentation/Annotate/annotate-label-editor#editor-layout).
</Note>

Mammography files can be arranged into a variety of different preset, or custom tile layouts.

<div>
  <img />
</div>

#### Presets

You can save presets for a given layout by typing a meaningful name after making a protocol selection, and clicking the **+** button. Click the tick icon next to a preset name to select the preset as your default layout.

#### Default layouts

You can specify any preset, including [*Auto layout*](#auto-layouts), as the default layout for studies in the Label Editor.

Click the tick icon next to a preset in the [hanging protocols menu](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#hanging-protocols), to select the preset as your default layout.

You can reset the Label Editor to the default layout by clicking the *Reset layout to default* icon.

<div>
  <img />
</div>

#### Auto layouts

<Note>
  Learn how to set the editor layout for the entire Project [here](/platform-documentation/Annotate/annotate-label-editor#editor-layout).
</Note>

Auto layouts are common layouts for viewing DICOM studies in the Label Editor. Auto layouts are set in the [DICOM editor settings](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#dicom-editor-settings). This includes the *MPR layout* setting, and the *Mammography layout* setting for mammography files.

Selecting the **Auto layout** option resets the Label Editor to your auto layout. You can specify the  **Auto layout** option as your [default layout](#default-layouts).

<div>
  <img />
</div>

Common mammography hanging protocols are available as presets in the [editor settings](#mammography-layout-settings). You can choose between the following mammography layouts:

* **Off**: Only the single mammography file that was opened is displayed in the Label Editor.

* **2x2**: Shows MLO views in the top row, and the CC views in the bottom row.

<div>
  <img />
</div>

* **4x1**: Shows CC on the left, and MLO on the right.

<div>
  <img />
</div>

<Tip>Hover over a mammography layout setting to see how each file will be displayed in the Label Editor if the setting is selected.</Tip>

***

## Study-wise navigation

Encord supports navigation on a study and series-level. Click the three dots icon to the submit button to choose between them.

* **Submit series** will submit the selected entity for review. For example - this means a single image for mammography, and a single volume for CT scans.
* **Submit study** will submit all series or entities in the study for review.

<div>
  <img />
</div>

***

## Mammography layout settings

The mammography layout settings are found in the DICOM editor settings of the DICOM Label Editor. The mammography layout settings determine the layout that mammography files are displayed in within the Label Editor.

<div>
  <img />
</div>

<div>
  <img />
</div>

You can choose between the following mammography layouts:

* **Off**: Only the single mammography file that was opened is displayed in the Label Editor.
* **2x2**: Shows MLO views in the top row, and the CC views in the bottom row.
* **4x1**: Shows CC on the left, and MLO on the right.

<Tip>Hover over a mammography layout setting to see how each file will be displayed in the Label Editor if the setting is selected.</Tip>


# Labeling Scenes
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-pcd



<Note>
  We strongly recommend enabling [graphics acceleration](https://www.howtogeek.com/412738/how-to-turn-hardware-acceleration-on-and-off-in-chrome/#:~:text=In%20the%20Settings%20menu%2C%20expand,Relaunch%E2%80%9D%20to%20apply%20the%20changes) in Chrome when working with PCD Scenes.
</Note>

## In-Editor Tutorials

Scene-type Projects include interactive in-editor tutorials that guide you through key annotation workflows step by step. Each tutorial auto-advances as you complete actions in the editor, so you get immediate feedback as you practice on a live scene.

<Note>
  In-editor tutorials are only available in Scene-type (3D LiDAR/point-cloud) Projects.
</Note>

### Cuboids across time

The **Cuboids across time** tutorial teaches you the full multi-frame cuboid tracking workflow. It takes approximately 5 minutes and covers the following steps:

1. Select an existing cuboid in the 3D view
2. Copy the cuboid to the clipboard
3. Navigate forward several frames and place the copied cuboid using `Shift + Click`
4. Interpolate between keyframes to fill in-between frames
5. View the cuboid's trajectory in the 3D view and on the timeline
6. Enable **Auto interpolate** in the editor settings so adjustments re-interpolate automatically
7. Edit the trajectory in grid view by dragging the cuboid in any frame column
8. Set the front face on the current frame using `Alt + Click`, or on every frame using `Alt + Shift + Click`
9. Toggle a keyframe using `Alt + K`
10. Lock the cuboid size to keep it uniform across all frames
11. Mark the object as static using `Alt + S`

The tutorial auto-advances when the editor detects you have completed each step. Step 5 (view the trajectory) requires you to click **OK** to advance manually. After you finish a step, you can click its title to re-expand and re-read the instructions at any time.

**To start the tutorial:**

<Steps>
  <Step title="Open the Help panel">
    Click the **Help** button in the top toolbar.
  </Step>

  <Step title="Navigate to Tutorials">
    Click **Tutorials** in the Help panel.
  </Step>

  <Step title="Start the tutorial">
    Find the **Cuboids across time** card and click **Start**.
  </Step>
</Steps>

***

# Label and Review Scenes

<Tip>
  We strongly recommend that Taskers use a mouse when annotating or reviewing Scenes. Using a mouse makes annotating or reviewing Scenes significantly easier.
</Tip>

1. Click **Start task** or **Initiate** to annotate a PCD data unit.

   The Label Editor opens with a PCD data unit ready for annotation.

2. Use the Editor controls and Toolbar buttons to navigate the PCD workspace.

3. Select an object label from the left-hand menu and begin annotating the PCD data unit.

4. Use your input device (mouse or trackpad) to create a label in the PCD workspace.

**Annotate Scenes manually**

<a href="https://www.loom.com/share/be8e5038ca854f8788a477711fa5d493" aria-label="Watch: Annotate - Scenes Manually" />

**Annotate Scenes automatically**

<a href="https://www.loom.com/share/238e9b19f22146d4ae4a58e6f04120d0" aria-label="Watch: Annotate - Scenes Automatically" />

## Scene Layouts

<AccordionGroup>
  <Accordion title="Configured layout">
    If a Scene has a configured layout, the Label Editor uses it to arrange 3D, camera, and time-series tiles and to select time-series channels for the timeline. If the configuration only specifies timeline channels, the editor retains the default tile arrangement and adds those channels to the timeline.
  </Accordion>

  <Accordion title="Image / Video without 3D channels">
    For Scenes that contain image or video channels but no 3D channels, the Label Editor automatically arranges the camera views in rows of up to two tiles. Channels with matching `left` and `right` names appear together first, with the left view before the right view. The remaining channels are ordered alphabetically, and an unpaired final channel appears in its own row.
  </Accordion>
</AccordionGroup>

# Navigating in the Scene

<Note>
  Context-sensitive keyboard hints display in the top-right corner of the 3D view.
</Note>

**Move**:

Use the <kbd>WASD</kbd> keys to move along the X axis in the workspace.

**Elevate**:

Use the <kbd>QE</kbd> keys to move along the Y axis in the workspace.

**Rotate**:

Hold down the scroll wheel and move your mouse to rotate.

**Pan**:

Hold down the right mouse button and move your mouse to pan around.

**Go Faster**:

Hold <kbd>Shift</kbd> while using the <kbd>WASD</kbd>, <kbd>QE</kbd>, or camera movement keys to move faster.

# Annotations

## Cuboids

### Automatically Create Cuboids

<a href="https://www.loom.com/share/c87ee9f981894709ac7ad725700ce3ae" aria-label="Watch: Auto Create Cuboids with One Click" />

**To automatically create a cuboid:**

1. Select a cuboid object from the left-hand navigation.
   A dialog box appears.

2. Click **One-click cuboid** button from the dialog.

   <Tip>Use the hotkey <kbd>J</kbd> instead of clicking the button.</Tip>

3. Hover over an object in the point cloud workspace.

4. Click the previewed cuboid to create the cuboid in the Scene.

### Smart Interpolation

<a href="https://www.loom.com/share/67bb0b8e453b4e4e8bbee49941b97ac0" aria-label="Watch: Smart Interpolation of Cuboids" />

Smart interpolation tracks a cuboid across frames directly from the point cloud. Instead of placing the cuboid manually on every keyframe, you click a cluster of points on different frames. Encord fits a cuboid to each cluster, then uses the motion of the cluster to interpolate the object's position on every frame in between.

Smart interpolation is available for **cuboid** objects in Scenes.

<Note>
  Smart interpolation uses a fitted ground mesh to track objects accurately as the terrain rises and falls. If no ground mesh is present, the **Smart interpolation** panel shows a reminder to add one. Use **Adjust ground** to fit a ground mesh that follows the terrain before you start adding keyframes.
</Note>

**To track a cuboid with smart interpolation:**

<Steps>
  <Step title="Create a cuboid keyframe">
    Place a cuboid on the object in at least one frame. You can draw it manually or use [One-click cuboid](#automatically-create-cuboids).
  </Step>

  <Step title="Start smart interpolation">
    Right-click the cuboid and select **Smart interpolation** (the magic-wand icon) from the context menu. The **Smart interpolation** panel opens.

    <Note>Smart interpolation is only available for a single, unlocked cuboid on an editable label in a Scene. It is not available for locked or approved labels, or in review and view-only modes.</Note>
  </Step>

  <Step title="Add keyframes by clicking clusters">
    Move to another frame and click a cluster of points that belongs to the object. Encord adds a keyframe and fits a cuboid to that cluster. Repeat on as many frames as you need — the more keyframes you add, the more closely the track follows the object.

    <Tip>Expand **Show how-to** in the panel for an illustrated reminder: *Click a cluster of points to add a keyframe. Right-click a new keyframe to remove it.*</Tip>
  </Step>

  <Step title="Adjust and finish">
    Fine-tune any keyframe (see below), then click **Finish** to write the interpolated track to the object. **Finish** becomes available once you have at least two keyframes. To leave without saving, click **Close** (the **X** in the panel).
  </Step>
</Steps>

#### Adjust keyframes in the interpolation preview

When a cuboid keyframe is active in the interpolation preview, use the standard cuboid controls to move, resize, or rotate it. Translation is available on all three axes, so the cuboid is not restricted to the ground plane. You can also use the keyboard shortcuts shown in the top-right corner of the 3D view, including <kbd>R</kbd> to switch between translation and rotation and <kbd>X</kbd>, <kbd>Y</kbd>, or <kbd>Z</kbd> to constrain the adjustment to an axis.

Enabled orthographic side views track the current preview cuboid on both keyframes and interpolated frames, helping you inspect its fit from multiple angles as you move through the preview.

#### Lock the cuboid size

By default, smart interpolation can resize the cuboid to fit the cluster on each keyframe. To keep the cuboid a consistent size across the whole track — useful for rigid objects such as vehicles — click the **Lock size** toggle (the padlock icon) in the top-right of the panel. Click it again to unlock. The size lock is stored per object, so it is remembered the next time you interpolate that cuboid.

#### Remove a keyframe

To remove a keyframe you added during smart interpolation, right-click it. The remaining keyframes are re-interpolated automatically.

### Cuboid trajectory in grid view

When you work in grid view with a cuboid selected, the top-down (bird's-eye) tile displays the selected cuboid's full trajectory path as a semi-transparent gray line. This gives you a spatial reference for the object's direction of travel across all frames, making it easier to verify and correct cuboid orientation without switching back to the main 3D view.

The grid-view timeline shows the frame ranges for the selected cuboid. While grid view is open, playback and frame navigation stay between the cuboid's first and last annotated frames. Use the frame skip control to move by one frame for precise adjustments or by five frames to move one grid window at a time.

<Note>
  The trajectory path only appears in the top-down tile of grid view. It does not appear in side-view tiles (front, back, left, right) or camera-view tiles. You must enable **Show Cuboid Trajectories** in the **Cuboid settings** section of the editor settings for the trajectory to display.
</Note>

<Tip>
  Use the trajectory overlay in the top-down grid tile to spot heading errors across keyframes — for example, when a vehicle's cuboid orientation does not match its direction of travel. You can correct the orientation directly in grid view without switching back to the main 3D view.
</Tip>

### Copy and pasting Cuboids

Copy labels from within the same frame using <kbd>Command + C</kbd> and <kbd>Command + Shift + V</kbd> on Mac, or <kbd>Ctrl + C</kbd> and <kbd>Ctrl + Shift + V</kbd> on Windows.

You can select multiple cuboids, copy them as a group, and paste them all at once onto any frame. The copied group moves together as a preview that follows your cursor, preserving each cuboid's relative position and orientation.

<Note>
  Only cuboid objects are included in a bulk copy/paste. If your multi-selection includes non-cuboid objects (such as polygons or polylines), those objects are not copied.
</Note>

Copy/paste keyboard shortcuts:

| Action                            | Windows                                | Mac                                       |
| --------------------------------- | -------------------------------------- | ----------------------------------------- |
| Copy selected cuboid(s)           | <kbd>Ctrl + C</kbd>                    | <kbd>Command + C</kbd>                    |
| Place copied cuboid(s)            | <kbd>Shift + Click</kbd>               | <kbd>Shift + Click</kbd>                  |
| Yaw-rotate group before placement | <kbd>R</kbd>                           | <kbd>R</kbd>                              |
| Select all cuboids                | <kbd>Ctrl + A</kbd>                    | <kbd>Command + A</kbd>                    |
| Clear clipboard                   | <kbd>Ctrl + C</kbd> (nothing selected) | <kbd>Command + C</kbd> (nothing selected) |

## Stereo Cuboid Tool

<a href="https://www.loom.com/share/435f96f6308648078cfdfe245c063ad1" aria-label="Annotate - Stereo 3D Scenes" />

The stereo cuboid tool provides an assisted workflow for creating and editing 3D cuboid annotations using camera image data. The stereo tool button, **Edit in stereo mode** context-menu option, and associated keyboard shortcuts are available in any Scene that contains at least one image or video channel.

<Note>
  The stereo cuboid tool is available for Scene-type datasets only. It requires edit permissions on the label and is not available on approved labels.
</Note>

<Warning>
  The stereo tool checks calibration data for each image at fit time. If your single camera image lacks calibration data, the tool may be available but the stereo fit could fail. Ensure your image has valid calibration data for best results.
</Warning>

<Tip>If you work with wide-angle or fisheye camera lenses and camera tiles appear cropped, enable **Render full camera image** in the [Editor settings](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts#scene) panel to display the full captured area.</Tip>

### Stereo cuboid keyboard shortcuts

| Action                | Windows                                               | Mac                                                   |
| --------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
| Activate stereo tool  | Stereo hotkey (`tools:stereo`)                        | Stereo hotkey (`tools:stereo`)                        |
| Toggle stereo preview | Stereo preview toggle (`tools:stereo-preview-toggle`) | Stereo preview toggle (`tools:stereo-preview-toggle`) |

### Edit in stereo mode

To edit an existing cuboid in stereo mode, right-click the cuboid annotation and select **Edit in stereo mode** from the context menu. This option is available in any Scene with at least one image or video channel.

## Toolbar

### Setting cuboid orientation

You can show or hide the orientation of cuboids using the "cuboid orientation" setting:

<a href="https://www.loom.com/share/a81402be62a7428baf485ad843e2c2d2" aria-label="Watch: Setting cuboid orientation" />

You can change the front face of a cuboid on the current frame by holding <kbd>Alt</kbd> (on Windows) or <kbd>Option</kbd> (on Mac) and clicking any face of the cuboid. The frame becomes a keyframe, and automatic orientation from motion does not override your selection during the current editor session. After you reopen the editor, a later automatic trajectory update may change that frame. This works whether the cuboid is selected or unselected.

When you hold <kbd>Alt</kbd> / <kbd>Option</kbd>, the drag-handle controls hide automatically so your click targets the cuboid face rather than a resize handle.

<Info>
  To change the front face across every frame where the cuboid exists, hold <kbd>Alt</kbd>+<kbd>Shift</kbd> (on Windows) or <kbd>Option</kbd>+<kbd>Shift</kbd> (on Mac) while clicking a face. Interpolated frames retain their interpolated status.
</Info>

<a href="https://www.loom.com/share/178f3470f0e64db9975404563050eded" aria-label="Watch: Change cuboid front face" />

## Point Cloud Filters

Click **Filters** in the toolbar to filter points by motion or height.

<AccordionGroup>
  <Accordion title="Color filter">
    The **Color filter** button appears in the 3D scene editor toolbar only when the loaded point cloud contains color or intensity data.

    <Note>
      The color filter applies globally to all loaded point clouds in the scene. When you enable the filter, points outside the selected range are hidden in the viewport and cannot be selected by any segmentation tool.
    </Note>

    **Enabling the filter**

    Click the **Color filter** button in the toolbar to toggle the filter on or off.

    **Filter modes**

    Open the **Color filter** popover (click the chevron next to the button) to configure the filter. Select a mode using the mode selector at the top of the popover:

    * **RGB** — Filter points by red, green, and blue channel ranges (0–255 per channel). Available when the point cloud contains file color data.
    * **HSV** — Filter points by hue, saturation, and value ranges. Available when the point cloud contains file color data.
    * **Intensity** — Filter points by intensity range (0–100%). Available when the point cloud contains intensity data.

    Use the range sliders to set the minimum and maximum values for each channel. Only points whose color or intensity falls within all specified ranges remain visible.

    **Eyedropper (Pick color from scene)**

    Click **Pick color from scene** in the popover to activate the eyedropper. Then click any point in the 3D viewport to seed the filter with that point's color or intensity. The sliders update automatically to a range centered on the sampled value.

    **Composition with other filters**

    The color filter works together with the height filter and slicer planes. A point must pass all active filters to remain visible and selectable.

    **Segmentation tool integration**

    When the color filter is active, the lasso, brush, and cuboid segmentation tools automatically exclude filtered-out points from selection. Only visible points can be selected.

    <Note>
      If the cuboid tool cannot resolve a point cloud in the rendered scene, it falls back to unfiltered selection for that cloud.
    </Note>
  </Accordion>

  <Accordion title="Motion filter">
    ### Motion filtering

    Under **Motion**, use **Show dynamic points** and **Show static points** to control which point classes the editor displays. When you change either setting for the first time, the editor analyzes the scene to classify its points.
  </Accordion>

  <Accordion title="Height filter">
    ### Height filtering

    The height filter lets you restrict which points the editor displays and which points segmentation tools can select, based on each point's height above a reference surface.

    #### Height filter modes

    The height filter offers two reference modes. The mode selector label updates dynamically depending on which ground reference is currently active:

    | Mode             | When available                           | Description                                                                                                                                           |
    | ---------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Ground plane** | Always                                   | Measures each point's height relative to the flat (or tilted) ground plane. The label changes to **Ground mesh** when a fitted ground mesh is active. |
    | **Ground mesh**  | Only when a fitted ground mesh is active | Measures each point's height above the local mesh surface rather than a flat plane. Use this mode for curved roads, slopes, and uneven terrain.       |
    | **World axes**   | Always                                   | Measures each point's height along the world vertical axis, ignoring any ground plane tilt or ground mesh.                                            |

    <Note>
      The **Ground mesh** option appears in the mode selector when you activate the automatically detected mesh using **Adjust ground** → **Use ground mesh**. If no ground mesh is active, the selector shows **Ground plane** instead.
    </Note>

    ### Using the height filter with a ground mesh

    <Steps>
      <Step title="Fit a ground mesh">
        Click **Adjust ground** in the toolbar, then click **Use ground mesh** when the automatically detected mesh is ready.
      </Step>

      <Step title="Open the height filter">
        Click **Filters** in the toolbar, then expand **Height**.
      </Step>

      <Step title="Select Ground mesh mode">
        In the mode selector, click **Ground mesh**. The histogram and min/max range update to reflect heights above the mesh surface.
      </Step>

      <Step title="Set your height bounds">
        Drag the slider or type values into the **Min** and **Max** inputs to define the height range you want to keep visible. To hide points identified as ground, click **Remove ground**. This sets the minimum height from the fitted mesh's detected ground level.
      </Step>
    </Steps>

    <Tip>
      Lasso (freehand) and brush segmentation tools respect the ground-mesh-relative height filter when **Ground mesh** mode is active. Only points above the mesh surface within your defined range are selectable.
    </Tip>

    <Info>
      The height filter range initializes to the 0.5th–99.5th percentile of point heights in the scene, giving you a wider default range that includes more of the point cloud.
    </Info>
  </Accordion>
</AccordionGroup>

## Label Branches

Label branches let you keep multiple versions of a Project's labels side-by-side. Use them to preserve a labeled state before a re-labeling pass, run an experiment without disturbing `main`, or hold a reviewer-only copy of labels.

<a href="https://www.loom.com/embed/795d49df662946d0b85bad2adc57ae2a" aria-label="Watch: Create & Display label branches" />

### Create Label Branches

Label branches are created in the [Label Checkpoint Workflow stage](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#branch-overlay-labels), or using the [SDK](/sdk-documentation/sdk-labels/sdk-label-versioning).

### View Label Branches

<div>
  <img />
</div>

<Note>
  This feature is only available to Workspace and Project Admins, and Team Managers in the REVIEW and COMPLETE Workflow stages.
</Note>

**To view labels from other branches:**

1. Click the **Branches** button in the Label Editor header.
   The branch overlay panel opens.

2. Select the checkboxes for the branches you want to overlay.
   Each branch displays with a unique color indicator.

3. Click outside the panel to close it.
   The selected branch labels now appear as read-only overlays in the 3D scene.

<Note>
  Branch label comparison is available in Review and Complete editor views — no feature flag or admin configuration required. Overlay labels are read-only. You cannot edit annotations from other branches directly in the overlay view.
</Note>

<Info>Audio and text-document modalities do not yet display branch names on overlay labels. The vertical fan-out uses fixed pixel offsets and is not collision-aware; in very dense scenes with many overlapping annotations, labels from multiple branches may still be difficult to read.</Info>

***

## Point Cloud Segmentation

### Automatically Create 3D Segmentations

<a href="https://www.loom.com/share/0c04dc688c8a4820a3969a6f05379284" aria-label="Watch: Auto Create 3D Segmentations" />

**To automatically create a 3D segmentation:**

1. Select a 3D segmentation object from the left-hand navigation.
   A dialog box appears.

2. Click **One-click segmentation** button from the dialog.

   <Tip>Use the hotkey <kbd>J</kbd> instead of clicking the button.</Tip>

3. Hover over an object in the point cloud workspace.

4. Click the previewed segmentation to create the segmentation in the Scene.

### Merge 3D segmentations

You can merge two or more 3D segmentations of the same Ontology class into one object. Select the segmentations in the timeline or the left sidebar, right-click the selection, and choose **Merge segmentations into** or **Merge into**. Then select the segmentation that you want to keep as the target.

The target keeps its object identity and class, and its segmentation includes all points from the merged objects. The other objects are removed.

### Scene Slicer

The Scene slicer isolates point cloud data so you can focus on a region and prevent points outside it from being selected for annotation. Click **Isolate points** in the 3D scene toolbar, then choose one of the following tools:

* **Box**: Drag a box around the points you want to keep.
* **Polygon**: Click around the points you want to keep, then press <kbd>Enter</kbd> or click **Submit** to close the polygon.
* **Split**: Click two points to draw a line, then click the side you want to keep.

You can combine up to six slices. Use **Reset** in the **Isolate points** pane to remove all slices, or use undo and redo to step through individual slicing changes. A polygon can contain up to 24 points.

# Editor actions

<AccordionGroup>
  <Accordion title="Center camera on origin">
    Hot key: <kbd>Shift + C</kbd>

    Brings the POV to origin. When you have an object selected (cuboid, keypoint, or polyline), this command centers the camera on that object instead of the origin.
  </Accordion>

  <Accordion title="Align camera with tile">
    Hot key: <kbd>ALT/OPTION + T</kbd>

    Brings the POV to the "tiles" listed in the drop-down that appears.
  </Accordion>

  <Accordion title="Adjust ground">
    Sets the position and rotation of the ground plane in the workspace. The ground plane is used for navigation (see "pan along ground" setting) as well as determining the initial position of cuboids.

    Click the ground plane icon in the toolbar to open the ground height controls:

    <img />

    **Auto-detection**: Encord detects and fits a terrain-conforming ground mesh in the background as the scene loads. Click **Use ground mesh** when it is ready. Click **Use ground plane** to switch back to the flat ground plane without discarding the detected mesh.

    <Note>
      Automatic ground segmentation is a preview capability. Advanced controls for ground mesh fitting parameters and the segmentation grid overlay are available in the debug panel for internal and developer users. Known limitations include reduced accuracy on steep slopes and uneven terrain in some configurations.
    </Note>

    **Set Manually**:

    * **Slider**: Drag to adjust the ground height. The range spans from the lowest to the highest point in the point cloud along the up axis.
    * **Visibility toggle**: Show or hide the ground grid overlay in the 3D view.
    * **Fit from 3 points**: Select 3 points on any point cloud to automatically fit the ground plane. This is useful when the ground is not flat or is at an angle.

      <Tip>
        You can also enter "Fit from 3 points" mode directly using the keyboard shortcut <kbd>Option + G</kbd> (Mac) or <kbd>Alt + G</kbd> (Windows), without opening the popover first.
      </Tip>

      When fitting mode is active, the toolbar button changes to show how many points remain to be picked:

    <img />

    Click 3 points on the point cloud surface to define the ground plane. The counter updates as each point is picked. Click the **x** on the button or press <kbd>Escape</kbd> to cancel.

    When the ground plane is rotated (tilted), rotation information is displayed in the controls. Use the **Reset rotation** button to return the ground plane to flat.

    When the ground grid is visible, it is displayed as a grid in the scene:

    <img />

    <Tip>For ground mesh fitting (an improved, terrain-conforming alternative to the flat ground plane), see the **Ground mesh fitting** settings below.</Tip>
  </Accordion>

  <Accordion title="Radius indicators">
    Hot key: <kbd>Option + R</kbd>

    Radius indicators are useful guides when annotating in 3D space. For example, you might only want to annotate anything that comes within 3 meters of your object (vehicle, robot, drone). You would then use a radius of three and only annotate anything within that radius.

    * `ON`: Displays one or more radii centered on the object (vehicle, robot, drone) that captured PCD. You can select the color used for all radii.
    * `OFF`: Hides all the radii.
  </Accordion>

  <Accordion title="Adjust scene origin">
    Specify custom or use "tile" coordinates as the Scene origin.
  </Accordion>

  <Accordion title="Merged cloud point view">
    Hot key: <kbd>ALT/OPTION + M</kbd>

    Displays point cloud data from multiple frames simultaneously in the workspace. When enabled, you can use the frame range controls to specify which frames to merge.

    * `ON`: Displays PCD from multiple frames at once. Click the dropdown arrow next to the button to access the controls.
    * `OFF`: Displays the PCD for the current frame only.

    <Note>
      By default, all frames in the scene are included when merged view is enabled.
    </Note>
  </Accordion>

  <Accordion title="Show points in images">
    Hot key: <kbd>ALT/OPTION + I</kbd>

    Displays point cloud data in 2D images.
  </Accordion>

  <Accordion title="Set camera target">
    Hot key: <kbd>CONTROL + ALT/OPTION+ C</kbd>

    Specify the camera target on a single point in the PCD data.

    <Tip>
      Use this feature with *Center camera on orign*.
    </Tip>
  </Accordion>

  <Accordion title="Scene view settings">
    Click **Scene view settings** on the right side of the 3D toolbar to display or hide elements in the PCD space.

    * `Show control hints`: Displays context-sensitive keyboard shortcut hints in the top-right corner.
    * `Show camera switcher`: Displays video views for the Scene.
    * `Show zoom indicator`: Displays zoom level information.
    * `Show size rulers`: Displays a scale ruler in the orthographic side views showing world unit measurements.
    * `Show camera target`: Displays the camera target in the 3D view.
    * `Show ground cursor`: Displays the ground-position crosshair in the 3D view.
    * `Show camera tiles`: Selects how camera tiles appear in the side work area.

    The **Show camera switcher** and **Show camera tiles** settings appear only when the Scene includes camera images.

    The zoom indicator is always displayed in the 3D view, except in first-person mode.

    When the Scene includes camera images, select **Camera** in the side work area or press `Shift + V` to switch between **3D** and **Camera** modes. Use **Follow camera target in camera views** to turn tracking on or off. When tracking is on, the side work area displays the camera views in which the selected cuboid is visible and focuses each view on the cuboid. If no cuboid is selected, the camera views follow the camera target. Hold `Ctrl` on Windows or `Command` on Mac while hovering over a valid point to preview that point as the target; when the preview ends, the camera views return to the camera target you set.
  </Accordion>
</AccordionGroup>

***

# Editor Settings

<AccordionGroup>
  <Accordion title="General settings">
    **Input Device**

    Specify using a `mouse` or `trackpad` to rotate or pan in the workspace.

    <Tip>
      We **STRONGLY** recommend using a mouse to rotate or pan in the workspace.
    </Tip>

    **Pre-load data**

    Pre-load data in the background for smoother navigation. Enabling this setting can improve performance when annotating or reviewing point cloud data.

    ***
  </Accordion>

  <Accordion title="Cuboid settings">
    **Face**

    Shows/Hides the "face" of cuboids in the PCD workspace.

    **Orientation**

    Shows/Hides the orientation of cuboids in the PCD workspace.

    **Set front face from motion**

    When enabled, Encord automatically orients the front face of a cuboid annotation based on the object's local direction of motion whenever you add or paste a keyframe. It ignores small movements caused by annotation jitter. Encord re-orients existing keyframes for that cuboid in the same operation, except for frames where you manually set the front face during the current editor session, so undoing the action also reverts the orientation change.

    <Note>
      This setting is disabled by default. When disabled, the front face follows how the cuboid was originally created. You can always set the front face manually at any time using `Alt+Click`.
    </Note>

    <Tip>
      Use **Set front face from motion** when annotating moving objects (such as vehicles or pedestrians) to keep cuboid orientations consistent with the direction of travel across all keyframes.
    </Tip>

    **Setting the front face manually with Alt+Click**

    Hold `Alt` and click any face of a cuboid to designate that face as the front face on the clicked frame. The frame becomes a keyframe, and automatic orientation from motion does not override your selection during the current editor session. After you reopen the editor, a later automatic trajectory update may change that frame. Hold `Alt+Shift` and click a face to set the front face across every frame instead. These shortcuts work whether the cuboid is selected or unselected.

    While you hold `Alt`, Encord hides the cuboid's drag-handle controls and makes the cuboid body the click target, so you can accurately pick the intended face without accidentally resizing the cuboid.

    When you set the front face across every frame, keyframes update their stored rotation, and interpolated frames rotate to match but retain their interpolated status.

    **Show Cuboid Trajectories**

    When enabled, Encord renders the selected cuboid's full trajectory path across frames. The trajectory path appears in the main 3D view and in the top-down (bird's-eye) tile of grid view, giving you a visual reference line for the object's direction of travel. The trajectory does not appear in front, back, left, right, or camera-view tiles — only the top-down tile shows it, because the path collapses to a point or line from those angles.

    <Tip>
      Use the trajectory path in the top-down grid view tile to verify and correct cuboid orientation against the object's actual direction of travel, especially when a vehicle or object has an incorrect heading across keyframes. You can do this without leaving grid view.
    </Tip>

    <Note>
      The trajectory overlay in the top-down grid tile requires **Show Cuboid Trajectories** to be enabled. Cuboids with only a single frame of annotation have no trajectory data and display nothing.
    </Note>
  </Accordion>

  <Accordion title="Helpers">
    **Ground**

    Shows/Hides the "ground" plane as a grid in the PCD workspace.

    **Axis**

    Shows/Hides the axis of the point of origin in the PCD workspace.

    **Cameras**

    Shows/Hides camera helper lines to aid in annotating PCD.

    **Background**

    Shows/Hides the background in the PCD workspace.
  </Accordion>

  <Accordion title="Color filter">
    Click **Filters** in the 3D Label Editor Toolbar, then expand **Color**. The section reports when the loaded point cloud has no color or intensity data.

    <Note>
      The color filter applies globally to all loaded point clouds in the scene. When you enable the filter, points outside the selected range are hidden in the viewport and cannot be selected by any segmentation tool.
    </Note>

    **Filter modes**

    Select a mode using the mode selector at the top of the section:

    * **RGB** — Filter points by red, green, and blue channel ranges (0–255 per channel). Available when the point cloud contains file color data.
    * **HSV** — Filter points by hue, saturation, and value ranges. Available when the point cloud contains file color data.
    * **Intensity** — Filter points by intensity range (0–100%). Available when the point cloud contains intensity data.

    Use the range sliders to set the minimum and maximum values for each channel. Only points whose color or intensity falls within all specified ranges remain visible.

    **Eyedropper (Pick color from scene)**

    Click **Pick color from scene** in the **Color** section of the **Filters** pane to activate the eyedropper. Then click any point in the 3D viewport to seed the filter with that point's color or intensity. The sliders update automatically to a range centered on the sampled value.

    **Composition with other filters**

    The color filter works together with the height filter and slicer planes. A point must pass all active filters to remain visible and selectable.

    **Segmentation tool integration**

    When the color filter is active, the lasso, brush, and cuboid segmentation tools automatically exclude filtered-out points from selection. Only visible points can be selected.

    <Note>
      If the cuboid tool cannot resolve a point cloud in the rendered scene, it falls back to unfiltered selection for that cloud.
    </Note>
  </Accordion>

  <Accordion title="Mesh asset settings">
    When a Scene contains mesh assets, use the Scene settings to inspect their geometry and appearance:

    * Use the switch for each mesh stream to show or hide that part of the asset.
    * Set **Mesh appearance** to **Textured** to display the asset's colors, or **Untextured** to apply a neutral fill that makes its shape easier to inspect.
    * With **Untextured** selected, enable **Faceted shading** to shade each triangle separately instead of smoothing the surface.
    * Adjust **Key light** to control directional shading and **Ambient light** to control the even fill light. These lighting preferences persist across sessions.

    Rest the pointer over a visible mesh to display its stream name and highlight that part.

    <Note>
      These settings appear only when the Scene contains a mesh asset. They do not affect point-cloud-only Scenes.
    </Note>
  </Accordion>

  <Accordion title="Point cloud settings">
    <Note>
      A Scene can optionally include view settings which will be applied when opening it, such as the point cloud size and coloring mode. See [Scene view settings](/sdk-documentation/index-sdk/sdk-scenes#scene-view-settings) to learn more.
    </Note>

    **Color settings**

    You can change the color of point cloud data in the PCD workspace. Here are the options:

    * **Solid**: Displays points with a single uniform color.
    * **Height**: Displays points in colors based on the distance from the "ground" plane.
      <Note>
        You can adjust the "ground" plane using the [ground height]() feature on the Editor toolbar.
      </Note>
    * **Provided**: Displays points in colors based on how they were originally captured and recorded. Available when a point cloud includes color data.
    * **Image**: Displays points in colors by projecting camera image data onto the points. Available when the scene includes cameras.
    * **Sensor**: Displays points colored by the sensor that captured them, making it easy to visually identify which sensor contributed which points in a multi-sensor setup. Available when the scene includes multiple point cloud streams.

    The settings panel does not show color modes that the scene data does not support. If a saved color mode is unsupported in a scene, the point cloud renders using **Solid**.

    The **Display point intensity** setting appears only when a point cloud in the Scene includes intensity data. The **sRGB color correction** setting appears only when the Scene includes provided point-cloud colors.

    <Note>
      * When you enable **Color by sensor** mode, points from different sensors are automatically assigned distinct colors from a fixed palette of 20 maximally distinct colors.

      * Sensor colors are assigned consistently based on the sensor's stream ID, so the same sensor is always use the same color across different frames and sessions.
    </Note>

    **PCD display settings**

    You can change the display settings of point cloud data in the PCD workspace. Here are the options:

    * Show: Displays point cloud data in the PCD workspace.
    * Merge: Displays all point cloud data across time in the PCD workspace.
    * Uniform size: Displays all point cloud data in a uniform size in the PCD workspace.
    * Hide segmented: Hides all point cloud data that is behind segmented objects in the PCD workspace.
      <Note>
        Only segmented objects that are set to be hidden hide all point cloud data behind them.
      </Note>
    * Hide Unsegmented: Hides all points not covered by any segmentation label. This toggle is off by default. You can also toggle this setting using `Shift`+`U`.

      <Note>
        When you enable **Hide Unsegmented** before creating any segmentations, no points are hidden because no segmentation coverage exists yet.
      </Note>

      <Note>
        You can combine **Hide Unsegmented** with **Hide segmented** to show only points that belong to visible segmentation labels.
      </Note>

      <Tip>
        Use **Hide Unsegmented** when trimming or refining segmentations on large point cloud scenes — hiding background points reduces visual clutter and prevents the brush and lasso tools from accidentally selecting unlabeled points.
      </Tip>
  </Accordion>

  <Accordion title="Point cloud size">
    Specify the size of cloud data points in the PCD workspace.
  </Accordion>

  <Accordion title="Point cloud opacity in 2D views">
    Specifies the opacity of PCD in 2D views.

    <Note>
      The default value is 0. PCD does not display in 2D views with a value of 0.
    </Note>
  </Accordion>

  <Accordion title="Render full camera image">
    Renders the full image captured by the camera beyond the source image's nominal bounds. Enable this setting when working with wide-angle or fisheye lenses in 3D scenes to display the complete captured area in the rectified camera view.

    <Note>
      This setting is off by default. When disabled, the rectified camera view clips to the source image's nominal bounds. This setting is only visible when you are working in a 3D scene context.
    </Note>

    <Tip>
      Enable **Render full camera image** when your camera tiles appear cropped. You can also search for this setting in the settings panel using keywords such as "fisheye", "wide-angle", "distortion", "rectified", or "clip".
    </Tip>
  </Accordion>

  <Accordion title="Ground mesh fitting">
    The ground mesh fitting tool improves ground detection in LiDAR/point cloud scenes, including curved roads and uneven terrain. Encord automatically detects and fits the mesh in the background as the scene loads. You can then activate it as an overlay in the 3D viewer, giving you a visual reference for scene geometry and making it easier to focus on objects of interest.

    **Ground segmentation**

    Encord automatically segments the point cloud into ground and non-ground points as the scene loads. Click **Adjust ground** in the toolbar, then **Use ground mesh** when the detected mesh is ready. To switch back without discarding the detected mesh, click **Use ground plane**. The segmentation algorithm handles curved and uneven terrain more accurately than a flat ground plane.

    **Height filter integration**

    When you fit a ground mesh, the **Height** section of the **Filters** panel gains a **Ground mesh** mode. In this mode, the height filter measures each point's height above the local mesh surface rather than a flat plane, enabling accurate filtering over curved or uneven terrain such as cambered roads or hilly ground.

    To use the height filter with a fitted ground mesh:

    1. Click **Adjust ground** in the toolbar, then click **Use ground mesh** when the detected mesh is ready.
    2. Close the **Adjust ground** pane.
    3. Click **Filters** in the toolbar, then expand **Height**.
    4. Select **Ground mesh** from the mode selector. The selector shows **Ground mesh** when a fitted mesh is active, or **Ground plane** when only a flat ground plane is available.
    5. Adjust the **Min** and **Max** bounds. The histogram and range reflect heights above the mesh surface.

    <Note>
      The **Ground mesh** option appears in the height filter mode selector only when a fitted ground mesh is active. If no ground mesh has been fitted, the selector shows **Ground plane** instead.
    </Note>

    Click **Remove ground** to set the minimum height from the fitted mesh's detected ground level and hide points identified as ground.

    Lasso (freehand) and brush segmentation tools respect the ground-mesh-relative height filter when **Ground mesh** mode is active, so only points above the mesh surface at the specified height range are included in your selection.

    To open or close the **Filters** panel, press `F`. Use the reset button beside **Height** to clear the height filter.

    When you select a cuboid and click **Level**, Encord aligns the cuboid with the local slope of the active ground mesh. If you use the ground plane instead, **Level** aligns the cuboid with that plane. The action preserves the cuboid's position, size, and heading.

    <Note>
      Cuboid fitting on the ground plane currently uses the flat ground plane, not the terrain mesh. Full integration with the terrain mesh is planned for a future release.
    </Note>

    <Note>
      Ground mesh fitting runs in the browser. On large or merged point clouds, the fitting process may temporarily affect UI responsiveness while it completes.
    </Note>
  </Accordion>

  <Accordion title="Faded point opacity">
    Specifies the opacity of data points that fade into the background. For example, all data points outside of a Scene slice.
  </Accordion>

  <Accordion title="Color points inside cuboids">
    Controls whether points that fall inside cuboids are highlighted with special coloring to make them more visible. This setting overrides the normal point coloring mode for points contained within cuboid annotations.

    | Option            | Description                                                          |
    | ----------------- | -------------------------------------------------------------------- |
    | **All cuboids**   | Highlights points inside every cuboid annotation (default behavior). |
    | **Selected only** | Only highlights points inside the currently selected cuboid.         |
    | **None**          | Disables cuboid point highlighting entirely.                         |

    <Tip>Use "Selected only" mode when working with many overlapping cuboids to focus on the cuboid you're currently editing.</Tip>
  </Accordion>

  <Accordion title="Label color mode (review)">
    Controls how 3D labels are colored during workflow review and consensus review tasks. This setting applies to all 3D label types: cuboids, spheres, polylines, and keypoints/points.

    <Note>
      This setting only takes effect when you are in a workflow review stage or consensus review stage. It has no effect outside of review tasks.
    </Note>

    **By review status**

    When you set **Label color mode (review)** to **By review status**, all 3D labels in the point cloud viewport are recolored according to their current review state:

    | Review state | Color  |
    | ------------ | ------ |
    | Pending      | Orange |
    | Approved     | Green  |
    | Rejected     | Red    |

    Labels you action (approve or reject) during the current review session fade to the opacity configured in **Reviewed label opacity**, reducing visual clutter as you work through the scene.

    <Note>
      The opacity fade applies only to filled shapes — cuboids and spheres. Polylines and keypoints/points are recolored by review status but do not fade.
    </Note>

    Selected 3D labels retain their review-status fill color when selected. Only the selection outline switches to the selection highlight color, matching the behavior in 2D review tasks.
  </Accordion>

  <Accordion title="Reviewed label opacity">
    Specifies the opacity applied to 3D labels that you have actioned (approved or rejected) during the current review session. Reducing this value fades reviewed labels into the background, making it easier to focus on labels that still require review.

    <Note>
      The opacity fade applies only to filled shapes — cuboids and spheres. Polylines and keypoints/points are recolored by review status but are not affected by this opacity setting.
    </Note>

    <Note>
      This setting only takes effect when **Label color mode (review)** is set to **By review status** and you are in a workflow review stage or consensus review stage.
    </Note>
  </Accordion>

  <Accordion title="In-editor tutorials (Scene projects)">
    Scene-type (3D LiDAR/point-cloud) projects include interactive in-editor tutorials you can access directly from the label editor. Each tutorial guides you through a specific workflow step by step, and the editor automatically detects when you complete each action so the tutorial advances in real time.

    **Accessing tutorials**

    Click the **Help** button in the top toolbar, then select **Tutorials**. The tutorials panel lists all available tutorials for your project type. Click **Start** on any tutorial card to begin.

    **Cuboids across time**

    The **Cuboids across time** tutorial teaches you the full multi-frame cuboid tracking workflow. It takes approximately 5 minutes and covers the following steps:

    1. **Select a cuboid** — select an existing cuboid in the 3D view.
    2. **Copy the cuboid** — copy the selected cuboid to the clipboard.
    3. **Place it on a later frame** — navigate forward several frames, then hold `Shift` to preview the copied cuboid and click to place it.
    4. **Interpolate between keyframes** — fill every frame between your two keyframes using the interpolate shortcut or the right-click menu.
    5. **View the trajectory** — review the trajectory the editor draws between keyframes, then confirm with **OK**.
    6. **Turn on auto re-interpolation** — enable **Auto interpolate** under **Drawing** in the editor settings so the editor automatically re-runs interpolation when you adjust a keyframe.
    7. **Edit the trajectory in grid view** — open grid view, drag the cuboid in any frame column to refine its position, and close grid view when done.
    8. **Set the front face** — use `Alt`+click to set the front face on the current frame, or add `Shift` to set it on every frame.
    9. **Toggle a keyframe** — use `Alt`+`K` to unmark or re-mark the current frame as a keyframe.
    10. **Lock the size** — click **Lock size** in the cuboid pane to enforce a uniform size across all frames.
    11. **Make it static** — use `Alt`+`S` or the pushpin in the cuboid pane to mark the object as static, copying its current pose to every frame.

    After you complete a step, the tutorial advances automatically. Step 5 (View the trajectory) requires you to click **OK** to advance manually. Once you finish a step, you can click its title to re-expand it and re-read the instructions at any time.

    <Note>
      The **Cuboids across time** tutorial is only available in Scene-type (3D LiDAR/point-cloud) projects. It does not appear for other project types.
    </Note>
  </Accordion>
</AccordionGroup>


# Labeling Text and HTML
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-text-html



Text files include formats such as `.txt`, `.md`, `.rst`, `.xml`, `.html`, `.json`, and more. However, HTML files are categorized slightly differently from other text file types. As a result, this documentation is divided into separate **Text** and **HTML** sections.

<Note> To learn how to import text and HTML see our documentation here.</Note>

<Info>
  The following types of labels can be applied to all text files, and at least one must be present in your project's ontology to enable text labeling:

  * **Text Region**: Object labels applied to a specific region within the text file.
  * **Classifications**: Classification labels applied to the entire file.
</Info>

## Readonly Text Tiles

When working with multi-tile layouts containing text files, individual tiles can be marked as read-only. Read-only text tiles prevent annotation creation or editing on those specific tiles while still allowing annotation on active, editable tiles within the same Task.

<Note>Read-only status applies at the tile level and affects both text region annotations and classifications for that specific tile.</Note>

<Tip>
  To copy selected text without creating an annotation, simply highlight the text you want to copy without first selecting an annotation tool. The text selection will remain active, allowing you to use `Ctrl+C` (Windows/Linux) or `Cmd+C` (Mac) to copy the content.
</Tip>

### Label Text and HTML Files

### Text

<div>
  <iframe />
</div>

<AccordionGroup>
  <Accordion title="Labeling Text Files">
    <Tip>
      Use `Ctrl+C` (Windows/Linux) or `Cmd+C` (Mac) to copy the selected text to your clipboard. and Use `Ctrl+V` (Windows/Linux) or `Cmd+V` (Mac) to paste.
    </Tip>

    #### Text

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label text files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-text-doc.gif)
  </Accordion>

  <Accordion title="Labeling JSON Files">
    #### JSON

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label JSON files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-json.gif)
  </Accordion>

  <Accordion title="Labeling XML Files">
    #### XML

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label XML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-xml.gif)
  </Accordion>
</AccordionGroup>

### HTML

Encord supports both raw HTML files and single-extension HTML files. The key difference is that single-extension HTML files include all the necessary elements to render the webpage, such as CSS and JavaScript.

<Tip>
  Use `Ctrl+C` (Windows/Linux) or `Cmd+C` (Mac) to copy the selected text to your clipboard. and Use `Ctrl+V` (Windows/Linux) or `Cmd+V` (Mac) to paste.
</Tip>

<div>
  <iframe />
</div>

<AccordionGroup>
  <Accordion title="Labeling HTML - Single Extension">
    #### HTML - Single Extension

    1. Click a *Text Region* label type (or use the hotkey)
    2. Highlight the text you want to apply the label to.

    ![Label HTML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-html-single-extension.gif)
  </Accordion>

  <Accordion title="Labeling HTML - Raw">
    #### HTML - Raw

    1. Click a *Text Region* label type (or use the hotkey)
    2. Highlight the text you want to apply the label to.

    ![Label HTML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-html-raw.gif)
  </Accordion>
</AccordionGroup>

### Using Relation Text Attributes - Text and HTML

Relation text attributes link an object to another object. In images or videos this could be linking a chicken's body to its wing. In PDFs or text documents (text or HTML files) this could be linking words with measurements, or linking words with other words.

<Note>
  Your Ontology must MUST contain text attributes with the Relation feature enabled if you want to use relation text attributes.

  ![Add Relation Text Attribute](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/project-ontologies-text-link.gif)
</Note>

While annotating, you can create a relationship between any object with a relation text attribute and any other object. After you create a relation between objects a workflow arrow points from the object with the relation text attribute to the other object.

![Link objects](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/annotate-project-link-text-region.gif)


# Time Series
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-time-series



<Warning>
  Time series is in Beta. Contact your Encord support representative to enable the feature for your Organization.
</Warning>

Time series data lets you import a CSV file and view its columns as charted channels in the Label Editor timeline.

<img alt="Time series data in the Label Editor" />

## Supported Files

Time series data currently supports CSV files with a MIME type of `text/csv` or `application/csv`.

Each file must contain a header row, at least one timestamp column, and at least one channel column.

```csv Example theme={"dark"}
time_ms,acc_x,acc_y,acc_z
0,0.12,0.02,0.98
100,0.18,0.03,1.01
200,0.15,0.01,0.99
```

### Columns structure

Time series CSV validation and parsing happen when the file is opened in the Editor. Encord makes the following assumptions about your CSV:

* The timestamp column is the first column whose header starts with `t`, `time`, or `timestamp`. If no matching header exists, Encord uses the first column.
* Timestamp headers can include a unit suffix, such as `time_ns`, `time_us`, `time_ms`, `time_s`, or `time_iso`. If the timestamp unit cannot be inferred, numeric timestamps are treated as frame-like values.
* Every non-timestamp column is treated as a channel and plotted in the timeline.
* Empty, `NaN`, `null`, or otherwise non-numeric channel values are treated as gaps.
* Rows without a valid timestamp are skipped.

<Note>
  These assumptions are temporary and in the future be optionally specified at upload time.
</Note>

## Register Time Series Data

Register time series CSV files with the `time_series` top-level key in your upload JSON.

```json Time series upload JSON theme={"dark"}
{
  "time_series": [
    {
      "objectUrl": "s3://my-bucket/sensors/session-001.csv",
      "title": "Session 001 telemetry",
      "clientMetadata": {
        "vehicle": "A-17",
        "route": "north-loop"
      }
    }
  ]
}
```

Then register the JSON file through the existing data registration flow:

* UI: [Manual Data Registration](/platform-documentation/Curate/add-files/index-register-cloud-data)
* SDK: [Import/Register Data](/sdk-documentation/getting-started-sdk/sdk-register-data)

## Annotating Time Series Data

Open a time series task in the Label Editor. The timeline displays the channels above the annotation rows. Annotators can use the chart as context while creating and reviewing time range labels.

For Composite Scenes, the timeline also displays each non-timestamp column from attached time series CSV streams. For MCAP Scenes with a configured layout, it displays the selected numeric time-series sub-channels.

To label intervals on a time series file, add a **Time range** object to your Ontology. Time range labels appear on the timeline and can be used to mark events, anomalies, or segments of interest.

The chart supports multiple channels. Channels are color-coded, and the timeline view can show time range labels below the chart. Time series uses the same timeline annotation interactions as other temporal modalities:

1. Select the **Time range** class.
2. Create a range on the timeline for the event or segment you want to label.
3. Adjust the range boundaries as needed.
4. Submit the task when all required labels are complete.

To display channel values when you hover over a chart, open **Visualization** and select **Show tooltip**. Encord saves this selection as a Label Editor preference. You can also toggle it from the Actions menu with **Show time-series tooltip**.

### Time Series in Data Groups

When a Data Group layout assigns a time series file to a tile, the Label Editor displays its channels in that tile instead of repeating them in the shared timeline. The chart stays synchronized with the group's frame navigation and displays the current frame cursor. Scroll to pan the chart. To zoom, hold <kbd>Ctrl</kbd> (Windows) or <kbd>Command</kbd> (macOS) while scrolling, or pinch on a trackpad. You can view existing time range labels, but you cannot create or edit ranges from the tile.

Use **Time series style settings** in the tile toolbar to display each channel as a line or points and adjust its line width or point size. Encord assigns different default colors to channels across time series tiles so that you can distinguish them.

### Customize Time Series Channels

Use the channel controls in the timeline to adjust how each CSV channel appears in the chart.

<div>
  <img alt="Time series channel color picker" />

  <img alt="Time series channel settings menu" />
</div>

You can:

* Hide or show individual channels.
* Set a custom channel color.
* Change the channel style between line and points.
* Resize the channel by changing line width or point size.

<Note>
  Customization of channel appearances is currently only possible while opening the time series in the editor, but will be possible at upload time in the future.
</Note>


# Videos & Image Sequences
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-videos



The following video goes through the basics of annotating videos in the Label Editor.

<div>
  <iframe />
</div>

***

## Navigation

Play/pause the video by clicking the *play/pause* button or by pressing <kbd>Space</kbd>. Skip through frames in the video with the <kbd>Left</kbd> and <kbd>Right</kbd> arrow keys or the forward and backward buttons. The number of frames skipped is determined by the specified *Frameskip interval*. *Frameskip intervals* can be set using the predefined values or customized by entering a value in the *New* input and clicking the **+** icon.

Control video playback speeds with the playback speed drop-down. *1x* is the set playback speed in the below example.

<div>
  <img />
</div>

Navigate through the video by scrubbing through or clicking anywhere on the progress bar.

<div>
  <img />
</div>

Navigate to a particular frame or timestamp by clicking the *compass* icon. Replace the value(s) with the desired target and click *Go*.

<div>
  <img />
</div>

Use the **Go to middle frame** action to instantly jump to the midpoint of the video. Access this action from the command palette (<kbd>Cmd</kbd>+<kbd>K</kbd> on Mac / <kbd>Ctrl</kbd>+<kbd>K</kbd> on Windows) or from the editor actions menu. This action has no default keyboard shortcut assigned. You can assign a custom shortcut to it through the hotkey customization settings in the Label Editor.

## Annotation Types

Objects are annotated using bounding boxes, polygons, polylines, keypoints or primitives. Frames are annotated using classifications. Instantiating objects or classifications in the video editor generates a *UUID* that uniquely identifies that instance across a range of frames (i.e., in the temporal dimension). The identifier is sometimes called a "track," with numerical IDs supplementing *UUIDs* for objects for visual aid.

Supported annotation types & corresponding features are listed in the table below. You can read more about the listed automation features <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-videos#automation">here</a>.

<Tip>
  Instances of all annotation types can be copied (<kbd> Ctrl</kbd> + <kbd>C </kbd>  /  <kbd> Cmd</kbd> + <kbd>C </kbd>),  and pasted at the location of the mouse cursor on a different frame by pressing (<kbd> Ctrl</kbd> + <kbd>V </kbd>  /  <kbd> Cmd</kbd> + <kbd>V </kbd>).
  Since it is the instance that is being copied and not simply the shape, it is not possible >to paste the instance on to the same frame.
</Tip>

| **Annotation type**    | **Dynamic attribute** | **Automated tracking** | **Interpolation** | **Import predictions** | **Model training & inference** |
| ---------------------- | --------------------- | ---------------------- | ----------------- | ---------------------- | ------------------------------ |
| Bounding box           | ✅                     | ✅                      | ✅                 | ✅                      | ✅                              |
| Rotatable bounding box | ✅                     | ✅                      | ✅                 | ✅                      | Coming soon                    |
| Polygon                | ✅                     | Coming soon            | ✅                 | ✅                      | ✅                              |
| Polyline               | ✅                     | ✅                      | ✅                 | ✅                      | Coming Soon                    |
| Keypoint               | ✅                     | ✅                      | ✅                 | ✅                      | ✅                              |
| Bitmask                | ✅                     | N/A                    | ✅                 | ✅                      | N/A                            |
| Object primitive       | N/A                   | ✅                      | N/A               | ✅                      | N/A                            |
| Frame classification   | N/A                   | N/A                    | N/A               | ✅                      | ✅                              |

***

### Bounding box

Creating a bounding box requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a bounding box annotation type. Instantiate a new bounding box instance by clicking on the specified class in the 'Classes' menu, or by using the specified hotkey (for example: <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

<div>
  <img />
</div>

Instantiating existing bounding box instances (i.e., bounding boxes that should keep the same identifier in preceding or succeeding frames) can be done by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>).

Bounding boxes can be copy/pasted between frames using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>C</kbd> to copy the object to the clipboard, and <kbd>cmd</kbd>/<kbd>ctrl</kbd>  + <kbd>v</kbd> to paste it at the location of the mouse cursor on the desired frame.

<div>
  <img />
</div>

Bounding box instances can be assigned with static and dynamic attributes should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified bounding box
* Assign a classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>).

<div>
  <img />
</div>

#### Tracking

Run automated object tracking by highlighting an object and clicking <kbd>shift</kbd> + <kbd>t</kbd> on your keyboard.

<div>
  <img />
</div>

Object tracking can also be run by selecting the option *Track from this frame* in the object menu. The number of predicted frames is set to *30* by default. The number of predicted frames can be changed in the 'Settings' drawer in the *Single object tracking settings* drop-down.

Click the *Automated labeling* button to open the 'Automated labeling' drawer to run multiple object tracking.

<div>
  <img />
</div>

You can read more about automated object tracking <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-videos#automated-object-tracking">here</a>.

#### Interpolation

Interpolation is run via the 'Automated labeling' drawer. Click the *Automated labeling* button to open the drawer. Select *Interpolation* from the drop-down menu, select the desired objects to interpolate, set the interpolation range (i.e., the range of frames) and click the *Run interpolation* button. Please note that you need a minimum two labels of an instance to run interpolation.

<div>
  <img />
</div>

You can read more about interpolation <a href="/platform-documentation/Annotate/automated-labeling/annotate-interpolation">here</a>.

### Rotating box

Traditional bounding boxes are great for annotating objects that appear in horizontal or vertical orientation, however, their accuracy may be limited when it comes to annotating objects at an angle. In such cases, use rotatable boxes to
produce more accurate annotations.

Creating a rotatable bounding box requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a rotatable box annotation type. Rotatable box labels can be assigned with static classifications should they be defined in your ontology.

Instantiate a new rotatable box label by clicking on the specified class in the 'Classes' menu or using the specified hotkey. Resize rotatable boxes like normal bounding boxes, and then grab the rotation handle to adjust the position until you're satisfied with the annotation's accuracy, as below.

<div>
  <img />
</div>

Rotatable bounding boxes can be copy/pasted between frames using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>C</kbd> to copy the object to the clipboard, and <kbd>cmd</kbd>/<kbd>ctrl</kbd>  + <kbd>v</kbd> to paste it at the location of the mouse cursor on the desired frame.

***

### Polygon

Creating a polygon requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a polygon annotation type. Enable or disable free-hand drawing mode by pressing <kbd>d</kbd> on your keyboard. Polygon coarseness for polygons drawn free-hand is set in the 'Settings' drawer in the *Drawing settings* drop-down. Instantiate a new polygon instance by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

A polygon can be closed by double-clicking anywhere on the canvas. Doing so will "snap" creating an edge between the last vertex to the first vertex drawn.

<div>
  <img />
</div>

Instantiate existing polygon instances (i.e., polygons that should keep the same identifier in preceding or succeeding frames) by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>). See the bounding box [documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#bounding-box) for visual instructions on how to instantiate existing polygons.

You can create polygons using SAM 2, by placing vertices, or by using the polygon brush (<kbd>F</kbd>).

Polygons can be copy/pasted between frames using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>C</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>V</kbd> to paste it at the location of the mouse cursor on the desired frame.

Polygon instances can be assigned with static and dynamic attributes should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified polygon.

* Assign classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>,
  <kbd>u</kbd>).

See the [bounding box documentation](#bounding-box) for visual instructions on how to assign classifications.

#### Interpolation

Run polygon interpolation following the instructions for bounding box, which you can find <a href="/platform-documentation/Annotate/automated-labeling/annotate-interpolation">here</a>. Unlike other linear interpolation methods, Encord's polygon interpolation algorithm does not require a matching number of vertices between polygon objects in set keyframes. Our algorithm also allows you to draw polygons in arbitrary directions (e.g., clockwise, counterclockwise, and otherwise).

#### Editing polygons with the brush tool

You can edit existing polygons with the brush tool. This allows you to create complex shapes in a much faster way than going vertex by vertex. To use the brush tool, select an existing polygon and then click on the brush tool button. This will show the brush tool settings panel where you can choose brush or eraser and change its size. Once you are done editing, click the "x" to go back to the label editor. Use the scissors tool if you'd like to remove vertices.

<div>
  <img />
</div>

### Polyline

Creating a polyline requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a polyline annotation type. Enable or disable free-hand drawing mode by pressing <kbd>d</kbd> on your keyboard. Polyline coarseness for polylines drawn free-hand is set in the 'Settings' drawer in the *Drawing settings* drop-down.
Instantiate a new polyline instance by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Polylines can be copy/pasted between frames using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>C</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>V</kbd> to paste it at the location of the mouse cursor on the desired frame.

Complete a polyline by double-clicking anywhere on the canvas.

<div>
  <img />
</div>

Instantiate existing polyline instances (i.e., polylines that should keep the same identifier in preceding or succeeding frames) by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>). See the [documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#bounding-box) for visual instructions on how to instantiate existing polylines.

Polyline instances can be assigned with static and dynamic attributes should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified polyline.

* Assign a classification by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>).

***

### Keypoint

Creating a keypoint requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a keypoint annotation type. Instantiate a new keypoint instance by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

<div>
  <img />
</div>

Instantiate existing keypoint instances (i.e., keypoints that should keep the same identifier in preceding or succeeding frames) by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>,
<kbd>w</kbd>, <kbd>e</kbd>). See the bounding box [documentation](#bounding-box) for visual instructions on how to instantiate existing keypoints.

Keypoints can be copy/pasted between frames using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>C</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>V</kbd> to paste it at the location of the mouse cursor on the desired frame.

Keypoint instances can be assigned static and dynamic attributes should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in
  the range overview for the specified keypoint.

* Assign classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>,
  <kbd>u</kbd>).

See the bounding box [documentation](#bounding-box) for visual instructions on how to assign classifications.

#### Automated tracking

Run automated keypoint tracking following the instructions for bounding box, which you can find <a href="/platform-documentation/Annotate/automated-labeling/annotate-sam">here</a>.

#### Interpolation

Run keypoint interpolation following the instructions for bounding box, which you can find <a href="/platform-documentation/Annotate/automated-labeling/annotate-interpolation">here</a>.

***

### Primitives

Creating a primitive (f.k.a. skeleton templates) requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a primitive annotation type. Use primitives to templatize shapes (e.g., 3D cuboids, pose estimation skeletons ) commonly used by your annotation team.

Instantiate a new primitive instance by clicking on the specified class in the 'Classes' menu or using the specified hotkey (e.g., <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Instantiate existing primitive instances (i.e., primitives that should keep the same identifier in preceding or succeeding frames) by clicking on the *Highlight* icon for the specified object or using the assigned hotkey (e.g., <kbd>q</kbd>, <kbd>w</kbd>, <kbd>e</kbd>). See the [bounding box documentation](#bounding-box) for visual instructions on how to instantiate existing primitives.

Primitives can be copy/pasted between frames using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>C</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>V</kbd> to paste it at the location of the mouse cursor on the desired frame.

Primitives allow you to define properties of edges defined in your template as visible, occluded, or invisible. Toggle the edge property settings for a primitive by highlighting the primitive and clicking the *Show controls* button.

<div>
  <img />
</div>

Primitive instances can be assigned with static and dynamic attributes should they be defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies):

* Highlight an object by clicking on it in the editor canvas or by clicking on the *Plus* icon or start/end frame in the range overview for the specified primitive.

* Assign classifications by clicking on the relevant buttons or using the set hotkeys (for example <kbd>q</kbd>, <kbd>u</kbd>)
  See the <a href="/platform-documentation/Annotate/annotate-label-editor/annotate-videos#bounding-box">bounding box documentation</a> for visual instructions on how to assign classifications.

#### Automated tracking

Run SAM 2 tracking following the instructions for bounding box, which you can find <a href="/platform-documentation/Annotate/automated-labeling/annotate-sam">here</a>.

#### Interpolation

Run primitive interpolation following the instructions for bounding box, which you can find <a href="/platform-documentation/Annotate/automated-labeling/annotate-interpolation">here</a>.

***

### Segmentation masks / Bitmasks

<div>
  <iframe />
</div>

Bitmasks allows you to create labels using a brush tool to select parts of an image. This can be useful when creating labels for vessel outlines, or labeling topologically separate regions. Bitmasks can be copy/pasted between frames using <kbd>cmd</kbd> (MacOS)/<kbd>ctrl</kbd> (Windows) + <kbd>C</kbd> to copy the object to the clipboard and <kbd>cmd</kbd>/<kbd>ctrl</kbd> + <kbd>V</kbd> to paste it at the location of the mouse cursor on the desired frame.

<Note>
  When creating a bitmask, the process continues until you press the <kbd>ENTER</kbd> or <kbd>ESC</kbd> key. This allows you to easily create complex bitmask labels without interruption.
</Note>

<div>
  <img />
</div>

<Note>Creating a bitmask segmentation requires an Ontology with the *Bitmask* annotation type.</Note>

<Tip>[Existing Bitmask labels can be updated](#updating-bitmask-labels) using the [brush tool](#brush-tool), [threshold brush](#threshold-brush), and [eraser](#eraser) tools.</Tip>

#### Brush tool

When selecting the bitmask annotation type, the brush tool is selected by default. Adjust the size of the bitmask brush tool using the slider in the bitmask popup.

<Tip>
  The brush tool is selected using the <kbd>f</kbd> hotkey when the bitmask popup is open.
</Tip>

When your label is ready, click **Apply label**, or press <kbd>Enter</kbd>.

#### Panoptic mode

<div>
  <img />
</div>

Panoptic settings allow you to determine how different bitmasks interact with one another.

* **None**: Overlapping bitmasks are allowed. The bitmask overlaps with existing bitmasks.
* **Exclude**: Areas already covered by a bitmask are excluded from the bitmask.
* **Overwrite**: Areas already covered by a bitmask are overwritten by the new bitmask.

#### Thresholding

The *Thresholding* tool enables you to set a threshold that determines the parts of the image or frame that is labeled by the Bitmask. Consequently, only the parts of the image falling within th predefined range are labeled upon selection with the *Thresholding* tool, ensuring precise and targeted labeling.

<div>
  <img />
</div>

When *Thresholding* is enabled, a mask covering the parts of the image that fall above the set threshold appears on the slice. This allows you to preview which parts of the image are labeled when a Bitmask label is applied. The mask color can be changed by clicking the circle icon.

The eyedropper tool enables you to pick a color or intensity value directly from the image.

Three different kinds of threshold can be selected using a dropdown:

* **Intensity**: Only pixels within the set intensity value range are labeled.
* **RGB**: Only pixels within the set [red, green, and blue](https://en.wikipedia.org/wiki/RGB_color_model) range are labeled. The range for each color can be set separately.
* **HSV**: Only pixels within the set [hue, saturation, and value](https://learn.leighcotnoir.com/artspeak/elements-color/hue-value-saturation/) range are labeled.

When your label is ready, click **Apply label**, or press <kbd>Enter</kbd>.

#### Eraser

The *Eraser* tool allows you to erase parts, or the entirety of your Bitmask selection if the **Apply label** button has not been clicked yet.

To select the threshold brush, click the eraser icon, or press <kbd>h</kbd> on your keyboard while the popup is open.

#### Combine bitmasks on an image/frame

Combining bitmasks on an image or frame allows you to label objects that are split/separated in the image/video frame.

<Note>
  When creating a bitmask, the process continues until you press the <kbd>ENTER</kbd> or <kbd>ESC</kbd> key. This allows you to easily create complex bitmask labels without interruption.
</Note>

**To combine two or more bitmasks on an image / video frame:**

1. Hold <kbd>SHIFT</kbd>.

2. Click the bitmasks you want to combine in the Label Editor workspace.

3. Right-click (on Mac press <kbd>Cmd</kbd>).
   A menu appears.

4. Select **Combine bitmasks into**.
   The bitmasks are now a single bitmask.

#### Bitmask overlap management

It is possible to prevent a Bitmask label from being overlapped by subsequent Bitmasks after the label is created. Use the toggle in the *Labels* section of the Label Editor to set the overlap behavior.

<div>
  <img />
</div>

Choose between the following settings:

<img />

* **Can be drawn over** -  If the Bitmask is drawn over, any part of the image beneath the existing Bitmask that falls within the specified threshold range is included in the next label.

<img />

* **Cannot be drawn over** - No part of the image covered by this Bitmask is included in any other Bitmask labels.

<img />

* **Must be drawn over** - If the Bitmask is drawn over, any part of the Bitmask label is included in the new Bitmask, regardless of threshold values set.

<Note>The  **Must be drawn over**  setting for *Bitmask overlap* is only available to select customers. Contact [support@encord.com](mailto:support@encord.com) for more information.</Note>

#### Updating bitmask labels

To update a bitmask label:

1. Click the bitmask label you want to edit.
2. Select either the [brush](#brush-tool), [threshold brush](#threshold-brush), or [eraser](#eraser) tool and make your changes.
3. Press <kbd>Enter</kbd> or click the **Update label** button in the bitmask popup.

#### Moving bitmasks

Bitmask labels can be moved to another location after being created.

1. Click the bitmask label you want to move.
2. Click and drag the bitmask to the desired location.
3. Release the bitmask to confirm the new location.

<img />

#### Downloading bitmasks as PNG

You can download bitmask annotations as PNG images directly from the video Label Editor on a per-frame basis. Each downloaded file includes the frame index in its filename for easy identification.

<Note>Bitmask PNG download exports the annotation for the current frame only. Downloading bitmasks across multiple frames simultaneously is not supported.</Note>

The editor provides three download options, all accessible via right-click context menus:

* **Single bitmask** — Right-click a bitmask annotation and select **Download bitmask as image**. The file downloads as a PNG named using the pattern `<data_title>_frame_<frame_index>_<annotation_name>_<object_id>.png`.
* **Multiple selected bitmasks** — Select multiple bitmask annotations (hold <kbd>Shift</kbd> and click each one), then right-click and select **Download bitmasks as image**. Encord composites all selected bitmasks into a single PNG named `<data_title>_frame_<frame_index>_bitmasks.png`.
* **All bitmasks on the current frame** — Right-click the canvas background and select **Download all bitmasks as image**. This option appears only when at least one bitmask exists on the current frame. Encord composites all bitmasks into a single PNG named `<data_title>_frame_<frame_index>_all_bitmasks.png`.

Special characters in the data title are replaced with underscores in the filename. Each bitmask renders in its assigned annotation color in the exported PNG. If the download fails, the editor displays an error notification.

***

### Frame classification

Creating frame classification(s) requires an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) with a classification annotation type. Frame-level classifications consider the frame as a whole, not the objects' localization. Instantiate a frame-level classification instance by clicking on the specified class in the 'Classes' menu or using the specified hotkey (for example: <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>).

Set the desired start and end frame by clicking the **Set start to current** and **Set end to current** buttons or using the set hotkeys <kbd>c</kbd> and <kbd>v</kbd>, respectively. Click the **This frame** button or the <kbd>x</kbd> hotkey to set the slider to only the current frame (e.g., frame 100). Add additional ranges by clicking the *Add range* button or pressing the <kbd>n</kbd> hotkey to add a frame range (e.g., if a car enters and leaves the frame throughout a video). Click the *Save* button or the <kbd>m</kbd> hotkey to save the instance. Use the **This frame & save** button or the <kbd>z</kbd> hotkey to classify and save the results for a single frame quickly.

<div>
  <img />
</div>

***

### Dynamic attributes

Encord supports dynamic attributes for all object annotation types (i.e., bounding box, polygon, polyline, keypoint, and primitives).

Highlight the desired object to assign dynamic attributes. Dynamic attributes are recognized by the *Dynamic* tag next to the given feature in the ontology. A dynamic attribute value applies across a range of frames, and its value can change over the object's lifetime. Each contiguous stretch of frames that shares the same value is shown as a colored segment (also called a *block* or *range*) on the attribute's sub-row in the timeline.

<div>
  <img />
</div>

#### Using dynamic attributes

The video tutorial goes through the basics of working with Dynamic Attributes in the Label Editor.

<div>
  <iframe />
</div>

Dynamic attribute values are stored and edited as **frame ranges** (blocks). Each block appears as a colored segment on the attribute's sub-row in the timeline, and a new block begins at every frame where the value changes.

#### How setting a value behaves

By default, when you set or change a dynamic attribute value at the playhead frame, the value applies **from that frame forward until the next point where the value changes**. If there is no later change, the value applies to the **end of the object's range**.

<Note>Because a change applies forward to the next change point, setting a value on a frame can overwrite later frames that were already correct, up to that next change point. To change only a single frame or a specific range, use **Limit to a single frame** or edit the block directly, as described below.</Note>

#### Set a value on a single frame

To apply a value to only the current frame without filling forward:

1. Open the **Timeline settings** menu in the video Label Editor.
2. In the **Dynamic attributes** section, turn on **Limit to a single frame**.
3. Move the playhead to the target frame, then set the attribute value in the left sidebar. The value is written only to that frame.

<Note>**Limit to a single frame** applies to every dynamic attribute edit while it is enabled. Turn it off to return to the default forward-fill behavior.</Note>

#### Set or edit a value on a specific range

To apply a value to an exact range of frames (for example, frames 12–16), or to adjust an existing block:

* **Create a new block** — On the attribute's sub-row in the timeline, drag from the start frame to the end frame to create a segment, then choose the value in the left sidebar. The value is written to exactly that range.
* **Resize a block** — Drag the left or right edge handle of a segment to change its start or end frame. Resizing overwrites any overlapping neighboring blocks for the same attribute.
* **Set exact bounds** — With a segment selected, type the exact **Range start** and **Range end** frame numbers in the left sidebar instead of dragging.
* **Delete a block** — Right-click a segment and choose **Delete**.

<Note>Editing a range that does not line up with the existing blocks (for example, setting frames 12–16 when the current blocks are 10–14 and 15–19) trims or overwrites the overlapping blocks. Create or resize the segment to the exact range you want, then set the value.</Note>

#### Propagate across gaps

The **Propagate across gaps** setting lets you apply a dynamic attribute value at the current playhead position and have it automatically cover all later sub-ranges of a sparse (non-contiguous) object, not just the current contiguous segment. This is useful when an object appears only on disjointed frame ranges (for example, every few frames) and you want to set a consistent attribute value across all its occurrences without manually visiting each one.

**To enable Propagate across gaps:**

1. Open the **Timeline settings** menu in the video Label Editor.
2. Navigate to the **Dynamic attributes** section.
3. Toggle **Propagate across gaps** on.

<Note>**Propagate across gaps** is off by default. When you enable **Limit to a single frame** at the same time, it takes precedence and **Propagate across gaps** has no effect.</Note>

**How propagation works:**

* When you set a dynamic attribute at the playhead, the value propagates forward through all later sub-ranges of the object, stopping only at the next frame where you have explicitly set a different value for that attribute.
* If you change or clear a propagated value mid-timeline, the edit propagates forward from that point through all later sub-ranges, while any later value you set explicitly is preserved.
* For checklist attributes, each option propagates independently. Only an explicitly set change to the same checklist option bounds propagation of that option — changes to other options do not stop it.
* Because a single range cannot span a gap in the object's presence, Encord stores cross-gap writes as one range per object sub-range.

<Tip>Use **Propagate across gaps** for the most efficient workflow on sparse objects: enable the setting, position the playhead at the first occurrence, set the attribute value, and Encord applies it to every later occurrence automatically.</Tip>

<div>
  <img />
</div>

**Typical workflow for a sparse object:**

1. Apply object labels to **all** relevant frames.

2. Add the [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) to the label in the first frame that the object appears in, and set its value.

3. Navigate to each point where the dynamic attribute changes value and set the new value there. Each change creates a new block that applies forward until the next change (or to the end of the object's range).

#### Frame labels tab

The *Frame labels* tab shows all instances with a label in the current frame. It is empty when there are no labels in a frame.

***

### Zoom and Sort By

<div>
  <img />
</div>

Zooming in on the timeline reveals finer time intervals, enabling precise identification of when object instances and classifications occur in the video. Conversely, zooming out provides a broader view of larger time segments.

You have the option to sort object instances and classifications either alphabetically or by their creation order. By default, the most recently created classes are displayed at the top.

### Selecting Objects and Instances

One or more objects and instances can be selected using the timeline. Simply click an object or instance on the timeline to select it. To select multiple objects or instances, click while holding down the <kbd>Shift</kbd> key.

Selected rows have a gray background and a green bar along the left edge, making single and multiple selections visible across the timeline.

Alternatively select an object or instance by right-clicking and choosing **Select**.

<div>
  <img />
</div>

### Moving Objects and Instances

Once objects and instances have been selected they can be moved to the top or the bottom of the timeline to suit your needs.

1. Select the instances and objects you want to move.
2. Right-click your selection.
3. Hover on *Move* when moving a single object or instance, and *Move all* when moving multiple objects or instances.
4. Select *To top* or *To bottom* depending on whether you want to move the object(s) and instance(s) to the top or the bottom of the timeline.

### Merging Instances on the Timeline

Multiple instances of the same object can be merged into a single instance of your choice, provided they don't appear on the same frame.

1. Select the instances you want to merge.

<Note>Hold <kbd>SHIFT</kbd> to select multiple instances.</Note>

2. Right-click your selection.
3. Hover on *Merge into*.
4. Select the instance you want to merge your selection into.

<div>
  <img />
</div>

***

### Fill Range to the Playhead

You can quickly snap the boundary of a selected classification range to the current playhead (the visual marker on the timeline) position using the **Fill to playhead** action. This is useful when you want to extend a range to an exact point without manually dragging the timeline handle.

<Tip>
  Position the playhead at the desired boundary point, select the classification range, then press `Alt+V` (Windows/Linux) or `Option+V` (Mac) to extend the nearest range edge to the playhead. You can also click **Fill to playhead** in the **Available Actions** panel in the left sidebar.
</Tip>

The action automatically determines which edge to move:

<Labelaudio />

<Note>
  **Fill to playhead** is only available for editable ranges. The action and hotkey have no effect on read-only or locked ranges.
</Note>

<Tip>
  Use **Fill to playhead** together with the other range-editing shortcuts for fast, keyboard-driven timeline work:

  | Action                          | Windows/Linux     | Mac                  |
  | ------------------------------- | ----------------- | -------------------- |
  | Fill selected range to playhead | `Alt+V`           | `Option+V`           |
  | Expand range right              | `Alt+Right`       | `Option+Right`       |
  | Shrink range right              | `Alt+Left`        | `Option+Left`        |
  | Expand range left               | `Alt+Shift+Left`  | `Option+Shift+Left`  |
  | Shrink range left               | `Alt+Shift+Right` | `Option+Shift+Right` |
</Tip>

### Editing Exact Classification Frame Ranges

When you select a classification in the left sidebar while the Label Editor is in edit mode, the frame range bounds display as editable **Range start** and **Range end** input fields instead of static text chips. This lets you type an exact frame number or timestamp to adjust a classification's range boundary directly, without needing to drag the timeline.

<Note>Editable range inputs are only available when the Label Editor is in edit mode, the classification is selected, and the label is not read-only. When these conditions are not met, the range bounds display as static text chips as before.</Note>

### Propagating Dynamic Attributes Across Disjointed Object Ranges

When an object appears only on disjointed (non-contiguous) frame ranges — for example, every few frames — setting a dynamic attribute normally writes only to the end of the sub-range containing the playhead. The **Propagate across gaps** setting changes this behavior so that the attribute value automatically covers all later sub-ranges of the same object.

To enable this setting, open **Timeline settings** and locate the **Dynamic attributes** section, then turn on **Propagate across gaps**. The setting is off by default.

When **Propagate across gaps** is on:

* Setting a dynamic attribute at the playhead propagates the value forward through all later sub-ranges of the object, stopping only at the next deliberately-set keyframe for that attribute.
* Editing or clearing a propagated value at any frame applies the change forward through all later sub-ranges from that point, while any deliberately-set later keyframe remains unchanged.
* For checklist attributes, each option propagates independently. Only a keyframe for the same checklist option stops propagation of that option — keyframes for other options do not affect it.

<Note>When **Limit to a single frame** is also enabled, it takes precedence and **Propagate across gaps** has no effect.</Note>

***

## Linking Objects

<Note>Object instances are linked using *Relation* attributes, which are set up in the Ontology. See our [documentation on *Relation* attributes](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#relation-attributes) to learn more.</Note>

1. Create both instance labels. In this example a chicken and its wing have been labeled using bounding boxes.

2. Click the *Edit classifications* button for the object with the *Relation* attribute. In the example this object is the wing, as seen below.

<img />

3. Click the *Set relation...* bar and select the instance you want to link the selected instance to. In our example the chicken and the wing appear on the same frame, and therefore appear under the *This frame* heading. Instances in different frames will appear under the heading *Rest*.

<img />

4. Click **Done**. The instances are now linked. This is shown in the *Instance labels* section with the name of the linked instance being displayed.

<img />

***

## Automation

Supported annotation types and available automation features are listed in the table below.

| **Annotation type**    | **Dynamic attribute** | **SAM 2 TRacking** | **Interpolation** | **Import predictions** |
| ---------------------- | --------------------- | ------------------ | ----------------- | ---------------------- |
| Bounding box           | ✅                     | ✅                  | ✅                 | ✅                      |
| Rotatable bounding box | ✅                     | ✅                  | ✅                 | ✅                      |
| Polygon                | ✅                     | ✅                  | ✅                 | ✅                      |
| Polyline               | ✅                     | ❌                  | ✅                 | ✅                      |
| Keypoint               | ✅                     | ❌                  | ✅                 | ✅                      |
| Bitmask                | ✅                     | ✅                  | ✅                 | ✅                      |
| Object primitive       | N/A                   | ❌                  | N/A               | ✅                      |
| Frame classification   | N/A                   | N/A                | N/A               | ✅                      |

***

### Interpolation

Encord's interpolation feature uses a proprietary linear interpolation algorithm that runs without using a representational model or matching pixel information in neighboring frames.

Our interpolation algorithm has been built with pragmatic usage in mind. For example, unlike other linear interpolation methods, Encord's interpolation algorithm does not require a matching number of vertices between objects in set keyframes. Our algorithm also allows you to draw object vertices in arbitrary directions (e.g., clockwise, counterclockwise, and otherwise).

<Tip>Use our [step-by-step guide](/platform-documentation/Annotate/automated-labeling/annotate-interpolation) to learn how to use the interpolation feature, and how to improve interpolation results using [re-interpolation](/platform-documentation/Annotate/automated-labeling/annotate-interpolation#3-re-interpolate).</Tip>

<div>
  <img />
</div>


# Label Multi-Modal Groups
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/multimodal-groups



This documentation provides specific information on annotating and reviewing [Data Groups](/platform-documentation/Curate/data-groups/index-data-groups) - including multi-modal groups in the Label Editor.

## Review Data Groups

Reviewing Data Groups requires you to switch between tiles to view annotations on each data unit. You can switch tiles by:

* Selecting the tile in the left-side menu.
* Clicking **Review from this tile** on a specific tile.

Both methods are synchronized. For example, clicking **Review from this tile** on a tile also selects it in the left-side menu.

<div>
  <img />
</div>

## Options and Settings

### Synchronized Zoom

When working with a Data Group, you can synchronize the zoom level and pan position across all tiles simultaneously. When enabled, zooming or panning in one tile automatically mirrors the same viewport to all other tiles in the Data Group.

<Note>
  Zoom synchronization applies to tiles containing images and videos. Tiles with 3D scenes or other non-2D content are not affected.
</Note>

To enable synchronized zoom:

1. Open the Data Group in the Label Editor.
2. Navigate to **Settings**.
3. Enable the **Sync zoom across tiles** toggle.

### Synchronize Playback

You can synchronize playback for all audio and video files. When enabled, playback on all media files occurs simultaneously.

<div>
  <img />
</div>

1. Open the Data Group in the Label Editor.
2. Click the *Synchronize timeline across files* button in the top-right corner.

<Note>
  To ensure all data units remain in sync, make sure they are all the same duration.
</Note>

### Single Editor Timeline Setting

To display only a single editor timeline for groups of data:

1. Click **Synchronize timeline across files** in the Label Editor toolbar.
2. Navigate to the *General* Settings.
3. Enable the *Single synchronized timeline* toggle.

<Info>
  The single editor timeline only shows annotations on the tile currently selected for annotation or review.
</Info>

<div>
  <iframe />
</div>

## Rearrange Tiles with Drag and Drop

When working with a carousel Data Group, you can drag items from the carousel strip and drop them into any mosaic tile pane. This lets you arrange DICOM series, PDFs, and other media across the multi-tile layout to suit your workflow.

<Steps>
  <Step title="Open a Data Group in the Label Editor">
    The carousel strip appears on the left or top of the editor, depending on your layout settings. Each item in the carousel displays a thumbnail preview.
  </Step>

  <Step title="Drag a thumbnail into a tile pane">
    Click and hold a thumbnail in the carousel, then drag it over the tile pane where you want to display it. A drop overlay highlights the target pane as you drag.
  </Step>

  <Step title="Release to open the item in that pane">
    Release the thumbnail over the target pane. The item opens in that tile, and the mosaic layout updates to reflect the new arrangement.
  </Step>
</Steps>

<Note>
  Thumbnails for items already open in a tile pane are not draggable. Only items that are not currently displayed in the mosaic can be dragged into a new pane.
</Note>

### Equalize the Mosaic Layout

The **Equalize Mosaic Layout** button in the editor header redistributes the available space equally across all open content panes. Use this to quickly reset an uneven layout after adding or rearranging tiles.

<Steps>
  <Step title="Open a Data Group with multiple tiles visible">
    Ensure you have more than one content pane open in the mosaic layout.
  </Step>

  <Step title="Click the Equalize Mosaic Layout button">
    Click the **Equalize Mosaic Layout** button in the editor header. Encord redistributes the pane sizes so each content tile receives an equal share of the available space. Carousel strip panes retain their configured size and are not affected.
  </Step>
</Steps>

## Cross-Tile Object Instantiation

When working with data groups, you can instantiate objects across multiple tiles for supported file types. This feature allows you to create annotations that span across different data units within the same group.

The **Instantiate object in frame** button appears in the annotation toolbar when:

* You're working with a data group containing supported file types
* Single synchronized timeline is enabled
* You have an object selected that can be instantiated across tiles

### Select Tiles

When using the configurable editor with a Data Group, the object table header includes a tile picker dropdown. This control lets you filter the instance list to a specific tile and set it as the active tile without leaving the object table.

* Select a specific tile from the dropdown to filter the instance list to that tile's annotations and set it as the active tile.
* Select **All tiles** to view instances across all tiles in the group.
* When **All tiles** is selected, the **Detect with SAM** (sparkles) and **Auto annotation** (wand) buttons in the object table header are disabled. Select a specific tile to enable them.

<Note>
  The tile picker in the object table header and the tile picker in the Bulk Operations drawer use the same underlying control. Selecting a tile in either location sets the active tile for the editor.
</Note>

<Info>
  The tile picker only appears in the object table when working with Data Groups in the configurable editor. For single data items, the object table shows all instances directly.
</Info>

### Read-Only Tiles

A dataset manager or admin can mark individual tiles in a Data Group as read-only when configuring a dynamic data group. When a tile is read-only, you can view its content but cannot add labels to it.

<Note>
  If you cannot annotate a tile in a Data Group, a dataset manager may have marked it as read-only. Contact your dataset manager if you believe this is incorrect.
</Note>

## Label-Branch Overlay for Data Groups

<Note>
  This feature is only available to Workspace and Project Admins, and Team Managers in the REVIEW and COMPLETE Workflow stages.
</Note>

<Tip>
  You can use the [Label Checkpoint Workflow stage](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#branch-overlay-labels) to create a new branch for your labels.
</Tip>

You can use the **Overlay label branches** button in the Label Editor header to visually compare labels from different branches simultaneously. When you select an overlay branch, the Label Editor renders that branch's labels in the branch's color on top of the active branch's labels, at the same time.

<Steps>
  <Step title="Open a Data Group in the Label Editor">
    Navigate to the Data Group asset you want to review.
  </Step>

  <Step title="Click the label-branch overlay button in the editor header">
    The overlay button appears in the annotation editor header. Click it to open the branch selector.
  </Step>

  <Step title="Select a branch to overlay">
    Choose the branch whose labels you want to compare. Encord renders that branch's labels in the branch's color on every tile in the Data Group simultaneously, on top of the active branch's labels.
  </Step>

  <Step title="Deselect the branch to clear the overlay">
    Click the overlay button again and deselect the branch to remove the overlay from all tiles.
  </Step>
</Steps>

<Note>
  The label-branch overlay button is only visible when the branch overlay feature is enabled for your environment. Contact your Encord administrator if you do not see the button in the editor header.
</Note>

### View Metadata for Data Groups

When working with Data Groups, you can view metadata for different data items within the Data Group using the metadata panel.

**Access Metadata Panel**:

1. Click the **Metadata** button in the Label Editor header to open the metadata panel.
2. The panel displays on the right side of the editor.

**Select Data Items for Metadata**:

When viewing a Data Group, the metadata panel includes a tile selector dropdown that allows you to choose which data item's metadata to view:

1. Open the **Metadata** panel.
2. Use the dropdown at the top of the panel to select between:
   * **Data Group** - Shows metadata for the entire Data Group
   * **Individual data items** - Shows metadata for specific files within the group

<Info>
  The tile selector only appears when working with Data Groups. For single data items, the metadata panel shows information for that item directly.
</Info>


# Create Ontologies
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies



An Ontology, also referred to as a taxonomy or labeling protocol, defines what is being labeled to make the data interpretable by computer vision applications. This structured framework categorizes the types of objects and concepts that are to be identified and annotated within images, videos, audio files, documents, and DICOM files.

<Tip>For more information on how Ontologies can be structured, see our [Ontology structure documentation](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies).</Tip>

## READ ME FIRST

The annotation landscape is vast. Encord provides an incredible amount of flexibility in how to create an Ontology. Your Ontology is a product of your needs. Here are a few things to keep in mind when building your Ontology.

<Accordion title="Rating Scales/Rubrics">
  Rating Scales or Rubrics are used for quality assessment or standardized evaluations of labels/classifications or data.

  <Tip>When using this type of annotation, consider using **Annotation instructions** with your Project. This allows you to keep your Ontology concise while providing more comprehensive information in your Annotation instructions.</Tip>

  * **Scale rating:** Balance simplicity and granularity in your rating. We recommend using a rating system of 0 to 5 or 0 to 7. This should provide enough accuracy while not overwhelming your annotators/reviewers.

  * **Object/classification description:** Keep Ontology option descriptions to 7 words or less, and use **Annotation instructions** for anything more detailed (30 words or less). Aim for a 9th grade reading level — plain language helps annotators work faster.

  * **Guidance:** Be concise while providing meaningful distinction between the scale rating options. Keep the guidance to a maximum of 3 words. 1 word is best.
</Accordion>

<Accordion title="Object labeling">
  You have a number of options when labeling objects: bounding boxes, polygons, bitmasks, and rotatable bounding boxes. Which label type depends on what you need to label and on the accuracy your use case requires. For example if you are annotating objects that are clustered together, using polygons or bitmasks provides more precise labeling. If objects are rarely close to each other or if you data displays only a single item at a time, bounding boxes could be used.
</Accordion>

<Accordion title="Primitives/Skeletons">
  Use primitives to label objects in cases where you need to break down a complex object into smaller parts or when you need to define a basic outline for complex structures. An example of this would be annotating people in poses or motion.
</Accordion>

## Create Ontologies

<a href="https://www.loom.com/share/fc71dbe55108474f93fe53ec9d249973" aria-label="Ontologies: Create Ontologies" />

<Note>We recommend learning about [Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) in Encord before creating Ontologies. </Note>

1. Click the **New ontology** button in the *Ontologies* section to create a new Ontology.

<div>
  <img />
</div>

2. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.

3. Click **Next** to continue.

<div>
  <img />
</div>

4. Define your Ontology structure. See our [documentation on Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) for more information on the various types of objects, classifications, and attributes.

**To add objects:**

<Warning>Ensure that you add *Audio Region* objects for audio files and *Text Region* objects for text files.</Warning>

<div>
  <img />
</div>

1. Click the **Add object** button.

2. Do one of the following:

   * Select a **Shared class**
   * Click **New Object**

   <Note>
     **Shared classes** cannot be edited while creating an Ontology. To edit a shared class go to the **Ontologies** > **Shared classes** page.
   </Note>

3. To create a new object, give the object a name. For example "Apple".

4. Select a shape for the object. For example *polygon*.

5. Optionally, enable the **Required** toggle to mark the object as *Required*.

6. Optionally, add attributes to the object.

7. Repeat these steps for as many objects as necessary.

**To add attributes to an object**:

You can add attributes to objects that define the object's characteristics. For example the object "Apple" can have an attribute "Color".

<div>
  <img />
</div>

1. Click the arrow icon next to an object to add attributes to the object.

2. Give the attribute a name. For example "Color".

3. Click the attribute type to change the attribute type. The default attribute type is a text field.

4. Click **Add option** to add an option, if you have chosen a radio button or checklist attribute.

5. Enter a name for the attribute option. For example, the attribute "Color" can have the options "Red", "Green", and "Yellow".

6. Click the **Back to parent** button to return the Ontology creation view.

**To add a classification**:

<div>
  <img />
</div>

1. Click **Add classification**.

2. Do one of the following:

   * Select a **Shared class**
   * Click **New classification**

   <Note>
     **Shared classes** cannot be edited while creating an Ontology. To edit a shared class go to the **Ontologies** > **Shared classes** page.
   </Note>

3. For a new classification, give the classification a name. For example, "Time of day".

4. Optionally, configure the classification. The default classification type is a text field.

5. Optionally, enable the **Required** toggle to mark the object as *Required*.

6. Repeat these steps for as many classifications as necessary.

**Configure classifications**:

You can configure classifications to change the classification type, and to add classification options to radio buttons and check lists.

<div>
  <img />
</div>

1. Click the arrow icon next to an object to configure the classification.

<div>
  <img />
</div>

2. Click the classification type to change the classification type. The default classification type is a text field.
3. Click **Add option** to add an option if you have selected a radio button or check list classification.
4. Enter a name for the classification option. For example, the classification "Time of day" can have the options "Night" and "Day".
5. Click the **Back to parent** button to return the Ontology creation view.

## Add Description

To give annotators clearer guidance on what to include and exclude, you can add descriptions to each element in your Ontology. This helps reduce confusion and leads to more accurate labels.

<Tabs>
  <Tab title="Adding Description">
    <div>
      <img />
    </div>
  </Tab>

  <Tab title="What Annotators See">
    <div>
      <img />
    </div>
  </Tab>
</Tabs>

## JSON Ontology Structure

You can preview a JSON of your Ontology structure when you are setting up or editing your Ontology. Preview the JSON by enabling the *Display JSON* toggle.

<div>
  <img />
</div>

## Ontology Best Practices

Creating an Ontology is a crucial step in developing effective machine learning applications. Keep the following considerations in mind when designing your Ontologies:

* **The Problem Domain**: Ensure your Ontology is exhaustive, with a class or representation for all important concepts. Consider the appropriate level of detail. For example, an application recognizing various animals might have top-level classes like "cat" and "dog," while one focused on dog breeds might use "German Shepherd" and "Border Collie" as top-level classes.

* **The Team**: Use terminology that is clear and communicable across your entire team, including annotators, reviewers, project managers, algorithm developers, and other stakeholders.

<Tip>
  We recommend adding descriptions to your Ontology to provide annotators with more details.
</Tip>

* **The Workflow**: Annotation can be difficult and time-consuming. Design your Ontology to represent classes and their attributes appropriately, but also aim for efficiency. Ensuring objects and scenes can be labeled both accurately and quickly will lead to a more efficient labeling process.


# Ontology Structure
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies



Ontologies are hierarchical structures that define the top-level concepts and categories in your data, along with nested attributes for detailed annotations. They consist of *Classes* at the top level, which can be either *Objects* or *Classifications*.

<Note>DICOM customers might be more familiar with the term 'labeling protocol', which is equivalent to an Ontology.</Note>

* **Objects**: Used to label specific locations in a frame, such as a car in a video frame.
* **Classifications**: Frame-level labels that do not have a specific location, such as indicating if an image is taken during the day or night.
* **Attributes**: These can be nested under objects, classifications, or other attributes to create detailed, hierarchical structures. For example, the object "horse" can have an attribute "color".

<div>
  <img alt="Ontology Nested Preview" />
</div>

## Ontology Structure

### Objects

**Objects** are configured with a title, an **object annotation type**, and optional **attributes**. You can also change their color.

<Tip>All objects can be marked as [*Required*](#mark-as-required).</Tip>

The following object annotation types are available:

| **Object**                 | **Description**                                                                                                                                                                                                                                                                          | **Supported For**                                                             |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Bounding Box**           | A quick-to-draw box shape compatible with many advanced automated labeling techniques.                                                                                                                                                                                                   | Single images, image groups, image sequences, videos, DICOM, NIfTI, Documents |
| **Rotatable Bounding Box** | A rotatable box for more accurate labels than standard bounding boxes.                                                                                                                                                                                                                   | Single images, image groups, image sequences, videos, DICOM, NIfTI, Documents |
| **Polygon**                | Captures complex shapes that bounding boxes cannot. Known as segmentations, polygons cannot be self-intersecting, but can be nested within other polygons.                                                                                                                               | Single images, image groups, image sequences, videos, DICOM, NIfTI, Documents |
| **Polyline**               | An unclosed polygon for representing long, thin annotations.                                                                                                                                                                                                                             | Single images, image groups, image sequences, videos, DICOM, NIfTI, Documents |
| **Keypoint**               | A simple geometric point for tracking small objects or specific points on larger objects.                                                                                                                                                                                                | Single images, image groups, image sequences, videos, DICOM, NIfTI, Documents |
| **Circle**                 | Creates a circular shape for labeling objects.                                                                                                                                                                                                                                           | Single images, Video, DICOM, NIfTI, Documents                                 |
| **Bitmask**                | Creates complex shapes with a brush tool, useful for parts of a frame or image. Multiple threshold filters can apply bitmasks to specific areas.                                                                                                                                         | Single images, image groups, image sequences, videos, DICOM, NIfTI, Documents |
| **Object Primitive**       | Previously called Skeleton template. A collection of connected geometric points, ideal for representing complex shapes like those in pose estimation. See [here](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#object-primitives) to learn more. | Single images, image groups, image sequences, videos, DICOM, NIfTI, Documents |
| **Audio Region**           | An object used exclusively to label parts of an audio wave. See our [documentation for labeling audio files](/platform-documentation/GettingStarted/gettingstarted-labeling#labeling-audio-files) to learn more.                                                                         | Audio                                                                         |
| **Text Region**            | An object used exclusively to label parts of a text document. See our [documentation for text files](/platform-documentation/Annotate/annotate-label-editor/annotate-documents#label-text-documents) to learn more.                                                                      | Text                                                                          |
| **Cuboid**                 | A quick-to-draw 3D box used to label objects.                                                                                                                                                                                                                                            | PCD (point cloud data) scenes                                                 |
| **3D Segmentation**        | Creates complex shapes in PCD scenes using a brush tool. All associated points become part of the same object.                                                                                                                                                                           | PCD (point cloud data) scenes                                                 |

### Classifications

<Info> Classifications are supported for all modalities </Info>

Since classifications apply to the entire frame, there is no need for specific colors or shapes. *Classification annotation types* include:

* **Checklist**: Allows multiple values. For example, "Weather" could be both cloudy and rainy.
* **Radio**: Allows a single value. For example, "Time of day" could be "Day" or "Night."
* **Text**: Allows freeform input for each situation.
* **Number**: Allows freeform numerical inputs.

<Note>Radio buttons can nest up to 7 layers deep. Check boxes and text fields do not support nesting.</Note>

<img alt="Ontology Classification Annotation Types " />

#### Global Classifications

Global Classifications apply to an entire file rather than a specific range of frames. To create one, enable the **Global** toggle when setting up a classification.

<Warning>
  Once an Ontology is attached to a Project, Global Classifications cannot be changed to non-Global Classifications.
</Warning>

<Info>
  Global Classifications are supported for all modalities.
</Info>

<div>
  <img />
</div>

#### Mark as Required

Any object, classification, or attribute can be marked as *Required*. This means annotators must include at least one instance of the required feature in each task before submitting.

<div>
  <img />
</div>

If annotators try to submit a task without including a *Required* object or classification, they see the following warning message.

<div>
  <img />
</div>

Click **View issue** to open the [Issues drawer](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments). From there annotators can seamlessly resolve all *Task requirement issues* before moving onto the next task.

<Tip>
  All *Required* objects and classifications create [*Task requirement issues*](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments).
</Tip>

### Attributes

***Attributes*** can be nested under objects or any classification with a *Radio* annotation type. To nest attributes, set the type to *Radio*, then click the **Configure** button next to the value where you want to add a new *attribute*.

<Tip>Attributes can be marked as [*Required*](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#mark-as-required), [*Dynamic*](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes), or [*Relation*](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#relation-attributes).</Tip>

<img alt="Configure Nested Attribute" />

### Nested Attributes

Ontologies support nested attributes on object and classification labels. This allows you to create hierarchical label structures. With nested attributes, you can define parent options that enable child options in a tree-based interface. This is particularly useful for creating complex taxonomies where certain sub-objects or sub-classifications only become relevant after selecting a parent category.

For example, you might create a "Quality" classification with options like "Good" and "Bad", where selecting "Good" enables additional severity options like "Minor" or "Major". This hierarchical approach helps organize complex labeling workflows and ensures annotators only see relevant options based on their previous selections.

<Note>Nested attributes are currently supported for radio buttons in object labels and classification labels.</Note>

### *Dynamic* Attributes

Top-level attributes can be marked as *Dynamic* to allow their values to change over time in a video. This is useful for representing temporary states—for example, a person can be labeled as "moving" in one segment and "stationary" in another.

<div>
  <img alt="Dynamic Attribute" />
</div>

<Tip>Refer to our [this documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#attribute-propagation--keyframes) to learn how to use dynamic attributes in the Label Editor, and apply dynamic attributes to a range of frames in a video.</Tip>

### *Relation* Attributes

The *Relation* attribute lets you link objects and define their relationship using free-text, regardless of annotation type.

<Note>
  Only one of the linked objects needs a *Relation* attribute for the link to be established. For example, to relate a chicken and a chicken wing, add a *Relation* attribute to either object in the Ontology.
</Note>

*Relation* attributes must be text fields (they cannot be radio buttons or checklists). They can be applied to any object label but not to classifications.

To create a *Relation* attribute, enable the *Relation* option when adding an attribute during Ontology setup. By default, it is named **#relation**.

<div>
  <img alt="Relation Attribute" />
</div>

<Note>Objects are linked in the Label Editor during annotation, not during Ontology creation.</Note>

**Using *Relation* attributes in the Label Editor**:

Once an Ontology with *Relation* attributes has been set up, instances can be linked in the Label Editor during annotation.

1. Create both instance labels. In this example a chicken and its wing have been labeled using bounding boxes.

2. Click the *Edit attributes* button for the object with the *Relation* attribute - in this example the chicken wing.

<div>
  <img />
</div>

3. Click the *Set relation...* bar and select the instance you want to link the selected instance to. In this example the chicken and the wing appear on the same frame, and therefore appear under the *This frame* heading. Instances in different frames appear under the heading *Rest*.

<div>
  <img />
</div>

4. Click **Done**. The instances are now linked. This is shown in the *Instance labels* section with the name of the linked instance being displayed.

<div>
  <img />
</div>

#### Apply to new occurrences

The *Apply to new occurrences* checkbox appears on the first instance of a label with a [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes). When selected, it applies the attribute value to all future labels of that instance.

<div>
  <img />
</div>

The *Apply to new occurrences* functionality also holds for instance labels created automatically using [interpolation](/platform-documentation/Annotate/automated-labeling/annotate-interpolation).

### *Transcript* Attributes

*Transcript* attributes are text fields for transcribing audio. Apply them to *Audio Region* objects and enter the transcription directly. For example, an *Audio Region* object called "Beautiful Voice" might use a *Transcript* attribute named "Lyrics" to transcribe song lyrics.

<Info>Only Text attributes can be marked *Transcript*</Info>

<div>
  <img />
</div>

### Name Attributes

*Name* attributes let users enter a name for an object directly within the Label Editor while labeling. This is useful for giving generic object classes more specific, descriptive names — for example, labeling speakers by name during audio transcription.

To create a *Name* attribute create a text attribute with `#name` before the name of your attribute.

<div>
  <img />
</div>

## Shared Classes

Shared classes are reusable Ontology components. You can create, edit and reuse object and classification label types using *Shared classes*. You can also view detailed version histories to track changes over time.

<Note>
  Editing a shared class that is used in a Project does not introduce breaking changes. You can add attributes to a shared class, but you cannot delete. You can archive attributes.
</Note>

### Create a Shared Class

You can create shared Object and Classification label types in **Ontologies** > **Shared classes**.

<div>
  <img />
</div>

**To create a new shared object:**

1. Click **Create new class**.

2. Select **Object** from the *Class type* field.

3. Type a meaningful name for the shared class.

4. Select the shared *Object type* to create. For example, select **Box** to create a bounding box object type.

<div>
  <img />
</div>

5. Click **Add attributes** > **Add attribute**.

6. Specify the settings for your object type attributes.

7. Rinse and repeat until your shared object is complete.

8. Click **Create class**.

**To create a new shared classification:**

1. Click **Create new class**.

2. Select **Classification** from the *Class type* field.

<div>
  <img />
</div>

3. Type a meaningful name for the shared class.

4. Click **Add attributes** > **Add attribute**.

5. Specify the settings for your classification attributes.

6. Rinse and repeat until your shared classification is complete.

7. Click **Create class**.

### Archive Shared Classes

When you archive a shared class that is used in existing Ontologies, Encord shows you which Ontologies use that shared class before confirming the archive action.

**To archive a shared class:**

1. Go to **Ontologies** > **Shared classes**.

2. Click the three-dot menu next to the shared class you want to archive.

3. Select **Archive**.

4. Review the confirmation modal that shows:
   * The name of the shared class being archived
   * A list of all Ontologies that currently use this shared class

5. Click **Archive** to confirm the action.

<Info>
  The confirmation modal includes direct links to each Ontology that uses the shared class, allowing you to review the impact before proceeding with the archive.
</Info>

<Note>
  Archiving a shared class removes it from future use but does not affect existing Ontologies that already use it. You can restore archived shared classes by selecting **Restore** from the same menu.
</Note>

### Edit Shared Classes

You can modify existing shared classes to add new attributes or update existing ones. When you edit a shared class, all existing attributes are preserved and displayed in the edit interface.

<Info>
  When editing shared classes in your Ontology, the **Global** toggle is disabled to maintain consistency across projects. Once a shared class is created with a specific global setting, this setting cannot be changed during editing to prevent conflicts in Projects that already use the shared class.
</Info>

**To edit a shared class:**

1. Go to **Ontologies** > **Shared classes**.

2. Click on the shared class you want to edit.

3. Click **Edit class**.

4. Make your desired changes:
   * Add new attributes by clicking **Add attribute**
   * Modify existing attributes by clicking on them
   * Archive attributes that are no longer needed

5. Click **Save changes** to apply your updates.

### View Shared Class Version History

The version history displays a chronological list of all versions, with the most recent version at the top. Each version entry shows:

* The user who made the changes
* The date and time of the modification
* Whether the version represents the initial creation or an edit

**To view version history for a shared class:**

1. Go to **Ontologies** > **Shared classes**.
2. Click on a shared class to open its detail panel.
3. Select the **Version history** tab.

### View Version Changes

Each version entry can be expanded to show detailed information about what changed in that specific version.

**To view changes in a version:**

1. In the **Version history** tab, click the expand arrow next to any version entry.

The expanded view shows specific changes made in that version, including:

* Added, deleted, or modified objects, classifications, and attributes
* Changes to properties like colors, shapes, or requirement settings
* Renamed features with before and after names
* Reordered attributes or options

<Info>
  The version history automatically loads additional versions as you scroll down. Click **Load more** if you need to see older versions.
</Info>

<Note>
  Version history is available for all shared classes and provides a complete audit trail of modifications made over time.
</Note>

## Allow Out of Bounds Labels

For bounding box object labels, you can enable the **Allow out of bounds** option. This permits annotators and reviewers to create bounding boxes that extend beyond the image boundaries in the Label Editor. This is particularly useful when objects are partially visible at the edges of images or when you need to capture the full extent of an object that extends beyond the frame.

When enabled, annotators can:

* Draw bounding boxes that start inside the image and extend beyond its edges
* Resize existing bounding boxes to extend beyond image boundaries
* Copy and paste bounding boxes that may extend outside the visible area

<Note>The **Allow out of bounds** option is only available for bounding box object labels and appears in the ontology form when you select the bounding box shape.</Note>


# Working with Ontologies
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies



## Edit Ontologies

You can edit any Ontology by updating its structure in the same way you did during the creation process. To edit an Ontology, simply select it from your list of Ontologies.

<Warning>
  Once an Ontology is attached to a Project, Global Classifications cannot be changed to non-Global Classifications.
</Warning>

### Required Settings for Global Features

When working with global objects and classifications in your Ontology, you can now modify the **Required** setting directly in the Ontology editor. This allows you to control whether global features must be completed during annotation, even after they've been shared across multiple projects.

<Note>
  The **Required** setting determines whether annotators must complete this feature before submitting their work. This applies to both global objects and global classifications.
</Note>

### Archive and Delete Entries

All Ontology entries can be either archived or deleted. The process is the same, but entries are archived when the Ontology is attached to Projects and can only be deleted when it is not.

<div>
  <img />
</div>

<Tip>
  Enabling the **Show archived** toggle at the top of your Ontology displays all archived entries in the Ontology.
</Tip>

### Duplicate Entities

During Ontology creation and modification, you can duplicate objects, classifications, and attributes. This can streamline creation of Ontologies that contain similar objects, classifications, and attributes.

When you duplicate an object, Encord automatically assigns a random color from the color palette to help distinguish it from the original object. Duplicated objects have *(copy)* appended to their name.

![Duplicate Objects and Attributes](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/ontology-duplicate-object-attributes.gif)

### Reorder Ontology

During Ontology creation and modification, you can adjust the order of objects, classifications, and attributes by dragging and dropping them.

![Adjust Objects and Attributes](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/ontologies-adjust-objects-attributes.gif)

### View Edit History

Encord tracks changes made to Ontologies each time the Ontologies are saved. Use the **Show version history** button on the Ontology's *Schema* page.

**To view an Ontology's edit history:**

1. Go to **Ontologies > \[select an Ontology]**.

   The *Schema* page for the Ontology appears.

   ![Show version history](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/Ontologies/annotate-ontology-show-history-01.png)

2. Click the **Show version history** button.

   The *Version history* panel appears from the right side of the screen.

   The *View changes* tab displays the following:

   * Name of the user that made an edit
   * Date and time an edit was made

3. Expand an entry in the *View changes* list.

   The edits made for an entry appear.

   ![View changes](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/Ontologies/annotate-ontology-revert-changes-01.png)

4. Click **View schema** to see a JSON of the entry version of the Ontology.

### Revert Ontology Edits

Encord tracks changes made to Ontologies. You can undo specific changes, while other changes need to be manually changed back.

<Note>
  An Ontology used by a Project provides a soft deletion (Archive) mechanism for objects, classifications, attributes, and options. Ontologies not used by a Project do not provide a soft deletion mechanism.
</Note>

**To restore archived features**

1. Go to **Ontologies > \[select an Ontology]**.

   The *Schema* page for the Ontology appears.

   ![Show version history](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/Ontologies/annotate-ontology-show-history-01.png)

2. Click the **Show version history** button.

   The *Version history* panel appears from the right side of the screen.

   The *View changes* tab displays the following:

   * Name of the user that made an edit
   * Date and time an edit was made

3. Expand the entry you need to revert in the *View changes* list.

   The edits made for an entry appear.

   ![View changes](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/Ontologies/annotate-ontology-revert-changes-01.png)

4. Turn on **Show archived**.

   ![Show archived](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/Ontologies/annotate-ontology-revert-changes-02.png)

5. Go to the Ontology setting.

   ![Revert changes](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/Ontologies/annotate-ontology-revert-changes-03.png)

6. Click **Restore**.

7. Continue as needed.

## Special Attribute Tags

When you create a **text attribute** on an Ontology object, you can give it special behavior by including a tag prefixed with `#` in the attribute's name. For example, adding `#name` to a text attribute uses that attribute's value as the object's display name in the Label Editor.

All special tags apply to **text attributes only**.

| Tag             | Applies to                              | How to enable                                               | What it does                                                                                                                                                                                         |
| --------------- | --------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `#name`         | A text attribute on any object          | Type the tag directly into the attribute's name (no toggle) | Uses the attribute's value as the **display name of the object instance** throughout the Label Editor (object lists, timelines, comments). If left empty, the object falls back to its default name. |
| `#relation`     | A text attribute on any object          | **Relation** toggle in the Ontology editor                  | Marks the attribute as a **relation** used to link one object to another object.                                                                                                                     |
| `#transcript`   | A text attribute on **audio** objects   | **Transcript** toggle (shown only for audio objects)        | Marks the attribute as **part of an audio transcript**, feeding the transcript view in the Label Editor.                                                                                             |
| `#text-content` | A text attribute on **polygon** objects | **PDF Text** toggle (shown only for polygon objects)        | Stores the **text selected on a PDF document** for that region.                                                                                                                                      |

<Note>
  `#relation`, `#transcript`, and `#text-content` are mutually exclusive: enabling one removes the others, because they define different roles a single text attribute can play. `#name` is independent and is the only tag set by typing it into the attribute name rather than using a toggle.
</Note>

<Tip>
  Tags are matched exactly and are case-sensitive (lowercase), so `#Name` does not work. A tag can appear anywhere in the attribute's name — for example `Speaker #name` — and the tag itself is hidden from annotators in the Label Editor.
</Tip>

## Ontology Settings

Select an Ontology, and navigate to the *Settings* tab to access the Ontology's settings.

### Copy Ontologies

An Ontology can be copied in the *Options* page of the Ontology's settings. Click the **Copy ontology** button to copy the Ontology.

<div>
  <img />
</div>

Copying an ontology copies all object primitives, and you have the option to copy any team members associated with the Ontology. The new Ontology is not attached to any Projects.

<Tip>
  You can also duplicate an Ontology directly from the Ontologies list by clicking the three-dot menu next to any Ontology and selecting **Duplicate**. A success message confirms when the duplication completes.
</Tip>

### User Management

users associated with the Ontology are managed in the *Team* pane of the Ontology's **Settings**.

**To add collaborators to the Ontology**:

<div>
  <img />
</div>

1. Search for the collaborator or the [group](/platform-documentation/General/general-workspace-settings#user-groups) you want to add. Multiple collaborators and groups can be added at once.

<Note>
  Only group members are added when a group is assigned to a Project. Group managers are not included.
</Note>

2. Select a user role.

* **User**: Can view the Ontology and attach it to Projects.
* **Admin**: Grants full administrative control over the Ontology.

3. Click **Add to ontology**.

<Info>
  * Change a user's role by clicking their role in the *Role* column and selecting a new one.
  * Remove users by clicking the *Delete* icon in the *Unassign* column.
</Info>

### Class Mappings

Ontology Class maps let you define named namespaces that map each Ontology class to an external identifier, most commonly a YOLO class number. Instead of re-entering class-number mappings every time you configure a label import/export, define them once on the Ontology and reference them by number in any import/export configuration.

<Note>
  When you configure a cloud label-export workflow node to use YOLO format, you select one of the Ontology's external-ID namespaces as the class mapping. Encord resolves class numbers live from the Ontology's current external IDs at export time. The mapping is not snapshotted when the node is saved. If you update class mappings after configuring the node, the changes take effect immediately on the next export.
</Note>

<Warning>
  Namespace names are case-sensitive. Use the exact same name when referencing a namespace in a YOLO label-export workflow node as you used when creating it.
</Warning>

**To configure class mapping namespaces for label import/export:**

1. Go to **Ontologies > \[select an Ontology] > Settings > Class mappings**.

2. Click **+ New mapping**.

3. Provide a meaningful name for the mapping. For example, `YOLO`. The name is what you select when configuring a YOLO label import or export.

4. Specify a number for each object label and classification in your Ontology.

5. Click **Save**.

<Tip>
  You can open the Ontology's class mappings settings directly from the cloud label-export workflow node settings panel by clicking the **Configure Ontology Mapping** link. This link opens the Ontology's external IDs settings page in a new tab.
</Tip>

### Object Primitives

Object primitives (formerly called *Skeleton templates*) are customizable Ontology class.

<AccordionGroup>
  <Accordion title=" Video Tutorial - Creating and using Skeletons ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

Object primitives are created in the *Object primitives* section of the *Settings* tab of an Ontology. Here you define a configuration of key points, and the vertices between them.

<img />

* **A**. 'Add a primitive': Start creating a new object primitive template.
* **B**. 'Names hidden': Show or hide the vertex names in the canvas.
* **C**. 'Add a point': Add more points on the canvas. Points are added to the list of points as they are made.
* **D**. 'Add an edge': Add more edges. Mouseover the first point and click once before clicking over the\
  end point of the edge. Edges are added to the list of edges as they are created.
* **E**. 'Move/edit': Move vertices. Mouseover the vertex you wish to move. Click and drag to move the target vertex to the new desired location.
* **F**. 'Save current state': Save the template. If you exit the editor screen without saving all your work will be lost.
* **G**. 'Name': Enter a name for this object primitive. This name will be displayed in the ontology structure *object annotation type* selection.
* **H**. 'Delete template': Delete this object primitive. Please ensure you've removed this object primitives from\
  all connected *objects* before deleting, or the ontology structure may enter an unstable state.
* **I**. 'Points': List of points with their coordinates and names. Coordinates are defined as (0, 0) in the\
  upper left. You can also add points using the **+ Add a point** button at the bottom of the list.
* **J**. 'Edges': List of edges. You can also add edges by using the **+ Add an edge** button at the bottom of the list.

**To create an object primitive**:

1. Click **Add a primitive** (A).
2. Give your primitive a meaningful name.
3. Click **Add**. You are now ready to set up your primitive.
4. Click **Add a point** (C). Add as many points as you need.
5. Select a point and press and hold **SHIFT** and then move to another point to create an edge. Add as many edges as you need.
6. Click **Save current state** (F) to save your primitive.

<Tip>You can adjust the color of points and edges by clicking the color circle next to their names in the list of points and edges.</Tip>

**To use your object primitive:**

1. Return to the *Schema* tab of your Ontology.
2. Click **+ Add object**.
3. Select your object primitive from the list of Object classes.
4. Save your Ontology.

<Tip> Learn how to work with Skeletons [here]() </Tip>

### Linked Projects

The *Linked projects* pane shows a list of Projects using the Ontology. You can jump to any of the projects displayed by clicking the **View** link.

<div>
  <img />
</div>

### Delete Ontology

Use the *Danger zone* pane to delete an Ontology.

<Note>Ontologies that are attached to one or more Project cannot be deleted. To delete an Ontology, it has to be removed from all Projects it is attached to.</Note>

<Warning>Note that deletion is a permanent action, and deleted Ontologies cannot be restored.</Warning>

<img alt="Screenshot of the ontology deletion pane" />

## View and join Ontologies in your Workspace

Workspace Admins can search for and join any Ontology that exists within the Workspace.

1. Navigate to *Ontologies* in the Encord platform.
2. Select the *All Encord ontologies* tab.
3. Find the Ontology you want to join.
4. Click **Join ontology** to join the Ontology.

<div>
  <img />
</div>

When a Workspace Admin joins an Ontology, they are automatically assigned the *Admin* [user role for that Ontology](/platform-documentation/Annotate/roles-and-permissions#ontologies).

<Tip>Ontologies can be filtered by Ontology owner.</Tip>

<Tip>See all the Ontologies you belong to by clicking the *Filter by* search bar, and selecting  *My ontologies only*. </Tip>


# Manage Annotation Projects
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects



1. In the Encord platform, navigate to **Projects**.
2. Select the Project you want to Manage.

<div>
  <img />
</div>

The dashboard is split into the following tabs:

* **[Project Overview](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#project-overview)**: High-level view of labeling and productivity statistics.
* **Explore**: Explore the distribution of instances and labels across data assets in the project.
* **[Queue](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-queue-%26-workflow)**: Shows all tasks in the Project by Workflow stage.
* **Workflow**: Graphically displays the path tasks follow through the Project Workflow.
* **[Analytics](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#analytics)**: Detailed Project analytics.
* **[Settings](/platform-documentation/Annotate/annotate-projects/annotate-project-settings)**: Manage your Project Settings, including copying Projects, managing Project tags, customizing editor layouts, and deleting Projects.

## Tab Visibility by Role

<Note>The *Analytics* and *Queue* tabs display different information based on the user's role. For more details, refer to the [Analytics dashboard documentation](#analytics).</Note>

<div>
  | **Tab**   | Annotator           | Reviewer           | Annotator + Reviewer            | Team Manager              | Admin                              |
  | --------- | ------------------- | ------------------ | ------------------------------- | ------------------------- | ---------------------------------- |
  | Summary   | ❌                   | ❌                  | ❌                               | ✅                         | ✅                                  |
  | Explore   | ❌                   | ❌                  | ❌                               | ✅                         | ✅                                  |
  | Queue     | *Annotate* tab only | *Review* tab only  | *Annotate* + *Review* tabs only | ✅                         | ✅                                  |
  | Workflow  | ❌                   | ❌                  | ❌                               | View only                 | ✅                                  |
  | Analytics | Personal analytics  | Personal analytics | Personal analytics              | Team analytics            | Team analytics                     |
  | Settings  | ❌                   | ❌                  | ❌                               | Add users (except Admins) | ✅ All settings and user management |
</div>

***

## Update Project Status

<div>
  <img />
</div>

Admins and Team Managers can change the status of a Project to any of the following:

* Not started
* In progress
* Paused
* Completed
* Cancelled
* Archived

<Info>Updating the Project status changes the Project icon accordingly.</Info>

When the Project status is changed to either *Paused*, *Completed*, or *Cancelled* then Annotators, Reviewers, and Annotator + Reviewers are prevented from opening tasks, and the **Initiate** button is grayed out. Admins and Team Managers are able to annotate and review tasks as usual, regardless of the Project status.

<Note>
  Tasks can still be opened using back door access. For example if an Admin shares a specific URL of a task with an Annotator, Reviewer, or Annotator + Reviewer.
</Note>

***

## Project Overview

The Project Overview dashboard provides a high-level summary of your Project's annotation health. It includes the **Project task status** chart and two analytics cards that surface class balance and issue tag patterns at a glance.

<Note>The analytics cards (**Class Distribution** and **Issue Tags**) are not shown for labeling-services-only Projects.</Note>

<Tip>Action buttons on configured overview cards (Data, Ontology, Project tags, and Annotation instructions) are hidden by default. Hover over a card to reveal its action button.</Tip>

<table>
  <thead>
    <tr>
      <th>Component</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Project task status**</td>
      <td>Displays the number of tasks that are in each stage of your Project. The number of stages and their names reflect the choices made during [workflow project selection/creation](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#creating-workflows).</td>
    </tr>

    <tr>
      <td>**Class Distribution**</td>

      <td>
        Shows the top 3 and bottom 2 annotation classes by label instance count, with a relative bar chart and percentage for each class. Classes that represent less than 10% of all label instances are highlighted in amber to flag potential data imbalance. When more classes exist than the visible limit, a truncation indicator (for example, "… 3 more classes") appears. The card header displays the total number of label instances created. Click **Open in Analytics →** to navigate directly to the **Labels** sub-tab of the **Analytics** tab.

        <br />

        <Note>Labels on Text and HTML files are not counted.</Note>
      </td>
    </tr>

    <tr>
      <td>**Issue Tags**</td>
      <td>Shows up to 5 of the most frequent issue tags with a relative bar chart and percentage for each tag. When more tags exist than the visible limit, a truncation indicator (for example, "… 2 more tags") appears. The card header displays the total number of open issues. Click **Open in Analytics →** to navigate directly to the **Issues** sub-tab of the **Analytics** tab.</td>
    </tr>

    <tr>
      <td>**Task layout**</td>
      <td>Displays the current task layout configuration for the Project. Shows **Standard** when the default layout is active, or **Custom** when a custom layout is configured. Click **Set up** to configure a custom layout, or hover over the card and click **Edit** to modify an existing custom layout. Click **Preview** to open an inline label editor preview in the right panel. Click **Close preview** to return to the analytics view. The **Preview** button is disabled when the Project has no demo data and no linked datasets — hover over it to see the tooltip "Link data to this project to see a preview".</td>
    </tr>
  </tbody>
</table>

![Annotate Summary](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/annotate-summary-01.gif)

### Overview Cards

The Project Overview page displays the following cards alongside the summary statistics. Each card shows relevant configuration details and provides quick-access action buttons that appear when you hover over the card.

| **Card**                    | **Configured state**                                                                                 | **Unconfigured / error state**                          |
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **Data**                    | Shows linked datasets. Hover to reveal **Manage** button.                                            | Shows **Configure** button persistently.                |
| **Ontology**                | Shows the linked Ontology. Hover to reveal **Edit** button.                                          | Shows **Add** or **Configure** button persistently.     |
| **Project tags**            | Shows applied tags. Hover to reveal **Edit**/**Done** toggle (users with tag-edit permissions only). | Edit button hidden if workspace association is missing. |
| **Annotation instructions** | Shows the uploaded file name with download and delete options. Hover to reveal **Replace** button.   | Hover to reveal **Upload** button.                      |

<Note>The **Edit** button on the **Project tags** card is only visible to users with tag-edit permissions. If your Project was created before you joined a workspace, you cannot use Project tags — create a new Project to enable this feature.</Note>

### Task Rules

<div>
  <img />
</div>

The **Task rules** section on the Project Overview tab summarizes the Project's label validation rules. Admins and Team Managers can click **Add task rules** to open **Manage rules**, where they can add, edit, or remove rules. Coverage and overlap rules apply to the whole task. You can configure minimum cuboid point-count rules for the whole task or individual cuboid Ontology classes.

<Note>
  Rules only appear in Projects that contain bounding boxes, rotatable bounding boxes, cuboids, segmentations, or bitmasks.
</Note>

Each role has the following enforcement levels:

* **Warning**: The Label Editor flags violations, but annotators can still submit the task.
* **Blocking**: Annotators cannot submit the task until they resolve all violations. The **Submit** button is greyed out, and hovering over it identifies the blocking rules.

| Rule                                  | Applies To                           | Description                                                                                                                                                                                       | Behavior / Notes                                                                                                                                                                                                                                                                                |
| ------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Required 3D segmentation coverage** | 3D scene (point cloud)               | Sets the minimum percentage of cloud points that must be covered by segmentations before a task can be submitted.                                                                                 | Helps enforce annotation completeness for point cloud segmentation tasks.                                                                                                                                                                                                                       |
| **Required bitmask coverage**         | Image or video tiles                 | Sets the minimum percentage of pixels that must be covered by bitmasks on every frame.                                                                                                            | Set to **0** to disable. Applies frame-by-frame across every frame in a tile.                                                                                                                                                                                                                   |
| **Prevent cuboid overlap**            | 3D scene (cuboids)                   | Warns annotators when cuboids overlap each other in the 3D scene.                                                                                                                                 | Overlaps surface in the rules panel and are highlighted in the editor.                                                                                                                                                                                                                          |
| **Prevent segmentation overlap**      | 3D scene (point cloud segmentations) | Warns annotators when point-cloud segmentations cover the same points within a label space.                                                                                                       | Overlapping pairs surface in the rules panel, grouped by the frames the space is active on.                                                                                                                                                                                                     |
| **Prevent bitmask overlap**           | Image or video tiles                 | Warns annotators when bitmasks cover the same pixels on a frame.                                                                                                                                  | Overlapping pairs surface in the rules panel, with an optional mode that highlights the overlapping regions in red.                                                                                                                                                                             |
| **Minimum points inside cuboid**      | 3D scene (cuboids)                   | Sets the minimum number of sensor points that must fall inside a cuboid.                                                                                                                          | Cuboids below this count are highlighted in the editor. Leave empty to disable.                                                                                                                                                                                                                 |
| **Constant cuboid size**              | 3D scene (cuboids)                   | Requires each cuboid to keep the same size across every frame where it appears. You can apply the rule to all cuboid classes or selected classes and optionally define one or more allowed sizes. | When multiple allowed sizes are configured, press <kbd>Tab</kbd> to cycle through them. Press <kbd>R</kbd> or <kbd>T</kbd> to rotate a fixed-size placement preview. The rules panel groups violations by object; use **Fix** to apply the first frame's size or an allowed size to all frames. |

Rule violations and their configured requirements appear in the Label Editor's Issues panel.

<div>
  <img />
</div>

## Manage Project Data

<div>
  <img />
</div>

You can manage the Datasets and storage folders attached to your Project using the **Project Data Management** modal in the **Overview** > **Data** section of your Project. The modal uses a three-panel layout:

* **Left panel** — Lists available datasets and storage folders with search and infinite scroll. Use the dropdown to select **All**, **Folders**, or **Datasets**. The **All** view searches folders and datasets together. Workspace Admins can also switch between sources available to them and all Workspace sources.
* **Center panel** — Displays a thumbnail grid preview of the selected dataset or folder's files. Use this panel to add or remove the selected source and configure folder-specific options.
* **Right panel** — Shows the Project's current data: the default dataset section and any additional datasets or folders, each with data-unit counts and status badges.

The modal footer tracks any unsaved changes. Click **Update project data** to apply your changes — Encord then refreshes all Project and dataset information automatically.

<Note>The exact button or menu that opens the Project Data Management modal may vary. Look for a **Manage** button on the **Data** card in the Project Overview, or check your Project settings.</Note>

### Add a Dataset

<Steps>
  <Step title="Open the modal">
    Open the **Project Data Management** modal from within your Project.
  </Step>

  <Step title="Select a dataset">
    In the left panel, select **Datasets** from the dropdown, then select the dataset you want to add.

    The center panel displays a thumbnail grid preview of the dataset's files.
  </Step>

  <Step title="Add the dataset">
    Click **Add dataset** in the center panel.
  </Step>

  <Step title="Save your changes">
    Click **Save** in the modal footer to apply the changes.
  </Step>
</Steps>

<Note>Live datasets (datasets backed by a storage folder) display a **LIVE** indicator in the **Project data** panel. New files added to the backing folder automatically appear in the Project.</Note>

### Remove a Dataset

<Warning>Removing an already-attached dataset requires confirmation. Encord displays a confirmation dialog before completing the removal.</Warning>

<Steps>
  <Step title="Open the modal">
    Open the **Project Data Management** modal from within your Project.
  </Step>

  <Step title="Select the dataset">
    In the left panel, select **Datasets** from the dropdown, then select the dataset you want to remove.
  </Step>

  <Step title="Remove the dataset">
    Click **Remove dataset** in the center panel, then confirm the removal in the dialog that appears.
  </Step>

  <Step title="Save your changes">
    Click **Save** in the modal footer to apply the changes.
  </Step>
</Steps>

### Add a Folder

<Steps>
  <Step title="Open the modal">
    Open the **Project Data Management** modal from within your Project.
  </Step>

  <Step title="Select a folder">
    In the left panel, select **Folders** from the dropdown, then select the folder you want to add.

    The center panel displays the folder's contents with options to select files and configure settings.
  </Step>

  <Step title="Select files">
    Choose which files to include. Select all files or toggle individual files as needed.
  </Step>

  <Step title="Configure Continuous Data Flow (optional)">
    Toggle **Continuous data flow** to control whether future files added to the folder automatically enter the Project.

    <Note>The **Continuous data flow** toggle is disabled when you select only a subset of items. Select all items to enable it.</Note>

    When **Continuous data flow** is on and you have active filters, new files pass through those filters before entering the Project.
  </Step>

  <Step title="Add the folder">
    Click **Add folder**.
  </Step>

  <Step title="Save your changes">
    Click **Update project data** in the modal footer to apply the changes.
  </Step>
</Steps>

### Update a Folder Configuration

After you add a folder to a Project, you can update its file selection, filters, or Continuous Data Flow setting.

<Steps>
  <Step title="Open the modal">
    Open the **Project Data Management** modal from within your Project.
  </Step>

  <Step title="Select the folder">
    In the left panel, select **Folders** from the dropdown, then select the folder you want to update.
  </Step>

  <Step title="Make your changes">
    Adjust the file selection, filters, or **Continuous data flow** toggle as needed.
  </Step>

  <Step title="Save the folder configuration">
    Click **Update** in the center panel to save the folder configuration.
  </Step>

  <Step title="Save your changes">
    Click **Update project data** in the modal footer to apply the changes to the Project.
  </Step>
</Steps>

***

**Explore tab**

<Note>The *Explore* tab is only visible to project Admins and Team Managers.</Note>

The *Explore* tab helps you understand how project annotations are distributed among data assets, at both an instance and label level. It allows a deeper exploration through attributes on objects, as well as frame-level classifications.

* Instance statistics: Class distribution across data assets in the given project.
* Label statistics: Label distributions within data assets, objects and classifications.

![Annotate Explore](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/annotate-explore.gif)

**Instance statistics**

This section provides the total count of all instances across the datasets in your project.

* **Project total**: Shows total instances (both objects and classifications) across the project by default. To get instance statistics for individual data files, click the drop-down to select a data file.
* **Select class**: Shows the total instances for a particular class. This is a summary of how a given class is distributed across your project's data assets. The pie chart segments show a breakdown of how that class is split across the data assets.
* **Display timestamps**: Flip the toggle to switch between frame numbers and timestamps for the labels.

**Label statistics**

This is a summary of how your labels are distributed across the project. The pie chart shows a breakdown of how many labels there are for a given class.

* **Project total**: Shows the total number of labels across different datasets in the project. To get label stats for individual data files, click the drop-down to select a data file.
* **Objects**: Click on the pie chart segment of a class to see the total number of labels and its attributes (sometimes called nested attributes) if available for that class.
* **Classifications**: Shows the global classification at project or individual video level. For example, location, time of day, etc.

***

## Task Queue & Workflow

Use the *Queue* tab to assign, prioritize, and manage tasks, and to start labeling and reviewing work. The *Queue* tab's layout adapts based on your role (Admin, Team Manager, Annotator, Reviewer, or Annotator + Reviewer).

<Tip>For the full Queue tab reference — including the task Status column, available filters, sorting, task actions (assign, release, move to stage, change priority), and Agent stage behavior — see the [Task Queue](/platform-documentation/Annotate/annotate-projects/annotate-workflow-queue) documentation.</Tip>

**Workflow tab**:

<Note>The *Workflow* tab is only visible to project Admins and Team Managers.</Note>

The *Workflow* tab lets you view and edit the Project's Workflow. To begin editing the Workflow, click the **Edit** button on the canvas.

The *Data* tab provides a complete overview of all tasks in the project, and lets you see which workflow stage each task is in.

## Save Label Version

<iframe title="YouTube video player" />

1. Click **Export** while in a Project.

<Info>Only Project admins can export labels</Info>

<Tip>Descriptions of all information contained in the export file can be found [in the export file reference](/platform-documentation/Annotate/annotate-export/annotate-export-json).</Tip>

<iframe title="YouTube video player" />

<Tip>
  To export labels for specific tasks:

  1. Select the tasks
  2. Click **Bulk actions**
  3. Select **Export**
</Tip>

1. Click **Export** while in a Project.

   The *Export labels* dialog appears.

2. Specify the following:
   * **Format:** Specify the format to export the labels (JSON or COCO).
   * **Stage:** Specify the Workflow stage to export the labels from.
   * **Generate signed URLs:** Specify whether to generate signed URLs for the data units that have labels.
   <Note>
     Enabling this option can significantly increase export times.
   </Note>
   * **Save as new version:** Specify to version the labels.
     * Provide a meaningful name for the label version.
   * **Labels to include:** Specify the labels to include. You can export all labels or select specific object or classification labels to export.

3. Click **Export**.

   A *Labels export in progress* toast message appears.

A *Labels export in progress* toast message appears.

4. Go to **Labels & Export > Versions**.

   The version of your labels appears in the *Versions* table.

Label versioning allows you to keep track of your label history over time by providing a snapshot of labels at a point in time. Label versions can be exported and analyzed to track annotation performance over time.

***

## Analytics

## Overview

### Project Overview Summary Cards

The **Overview** tab of your Project displays a set of summary cards that give you an at-a-glance view of Project health. These cards are hidden for labeling-services-only Projects.

**Top row — stat cards**

A row of three compact stat cards appears above the task-status chart:

| **Card**            | **What it shows**                                                           | **Footer link**                                                                           |
| ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Tasks completed** | Number of completed tasks out of the total, with a Project status selector. | Project status dropdown                                                                   |
| **Time spent**      | Total active time spent in the Label Editor across all collaborators.       | **Show breakdown** — navigates to the **Collaborators** analytics tab.                    |
| **Opened issues**   | Number of currently open (unresolved) issues in the Project.                | **Show tasks** — navigates to the Project queue filtered to tasks with unresolved issues. |

**Task status chart**

The task status bar chart displays the number of tasks at each stage of your Workflow. When no task data is available, the chart displays an empty state illustration with the message "Configure data to see tasks status" instead of a blank chart. Tooltips are also disabled in this state.

**Bottom row — distribution cards**

Below the task-status chart, two cards appear side by side:

* **Class Distribution** — shows the top 5 and bottom 5 Ontology classes by label instance count. The subtitle displays the total number of label instances. Click **Show analytics** to open the **Labels** analytics tab. When no label instances exist yet, the card displays "Instance labels by class will appear here."
* **Top Issue Tags** — shows up to 10 issue tags ranked by frequency, with amber-colored horizontal bars. The subtitle displays the total number of issue tags created. Click **Show analytics** to open the **Issues** analytics tab. When no issue tags are configured or used, the card displays an empty state with a **Setup issue tags** link to your issue-tag settings.

<Note>
  The tag counts on the **Top Issue Tags** card reflect tag-action totals (including re-rejections), not unique issue counts. The **No tag** bucket — representing issues with no tag applied — is an approximation and may show 0 even when untagged issues exist. An accurate untagged count requires a future backend update.
</Note>

### Workflow Mini-Map

Annotation, review, and other queue-type stage nodes in the mini-map are clickable. Clicking a stage node navigates you directly to the **Queue** tab, pre-filtered to that stage.

<Tip>
  A pointer cursor appears when you hover over a clickable stage node, indicating that you can click it to jump to the corresponding queue.
</Tip>

The following node types are not clickable and do not navigate to the Queue:

* **Start**
* **Percentage Router**
* **User Router**

## Analytics

The *Analytics* tab of your Project shows event-based analytics for your Project's tasks, labels, and users. The *Analytics* tab has the following views:

* [**Tasks**](#tasks): View analytics on specific tasks in your Project.
* [**Labels**](#labels): View analytics of labels in your Project.
* [**Collaborators**](#collaborators): View collaborator performance in your Project.
* [**Issues**](#issues): View analytics relating to issues in your Project.
* [**Agents**](#agents): View analytics relating to Agent stages in your Project.

<Tip>
  The **Class Distribution** and **Top Issue Tags** cards on the Project Overview provide quick access to the **Labels** and **Issues** sub-tabs of the Analytics section. Click **Show analytics** on either card to navigate directly to the corresponding detailed view.
</Tip>

<Info>
  The analytics available on the Analytics dashboard vary based on user roles:

  * **Admins and Team Managers** have access to the *Tasks*, *Labels*, and *Collaborators* views, offering a comprehensive overview of team performance.
  * **Annotators**, **Reviewers**, and **Annotator + Reviewer** roles can only view the *Task Actions*, *Time Spent*, and *Label Actions* tables, limited to their individual contributions.
</Info>

<Warning>
  Actions performed in the Label Editor or using the SDK are only tracked on the *Analytics* dashboard if they the tasks are actioned (submitted/rejected/approved).
</Warning>

Project Analytics have the following filters:

| **Filter**             | **Description**                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| **Collaborators**      | Filter by specific Project collaborators.                                                         |
| **Datasets**           | Filter tasks based on the dataset they belong to.                                                 |
| **File name includes** | Filter by file name. Regex is supported, allowing filtering by prefix or infix in the file title. |
| **Event source**       | Filter by the source of the event. Either SDK or UI.                                              |
| **Workflow stage**     | Filter tasks based on their current stage in the Workflow.                                        |
| **Class**              | Filter by Ontology class.                                                                         |

**Top row — stat cards**

A row of three compact stat cards appears above the task-status chart:

| **Card**            | **What it shows**                                                           | **Footer link**                                                                           |
| ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Tasks completed** | Number of completed tasks out of the total, with a Project status selector. | Project status dropdown                                                                   |
| **Time spent**      | Total active time spent in the Label Editor across all collaborators.       | **Show breakdown** — navigates to the **Collaborators** analytics tab.                    |
| **Opened issues**   | Number of currently open (unresolved) issues in the Project.                | **Show tasks** — navigates to the Project queue filtered to tasks with unresolved issues. |

**Bottom row — distribution cards**

Below the task-status chart, two cards appear side by side:

* **Class Distribution** — shows the top 5 and bottom 5 Ontology classes by label instance count. The subtitle displays the total number of label instances. Click **Show analytics** to open the **Labels** analytics tab. When no label instances exist yet, the card displays "Instance labels by class will appear here."
* **Top Issue Tags** — shows up to 10 issue tags ranked by frequency, with amber-colored horizontal bars. The subtitle displays the total number of issue tags created. Click **Show analytics** to open the **Issues** analytics tab. When no issue tags are configured or used, the card displays an empty state with a **Setup issue tags** link to your issue-tag settings.

<Note>
  The tag counts on the **Top Issue Tags** card reflect tag-action totals (including re-rejections), not unique issue counts. The **No tag** bucket — representing issues with no tag applied — is an approximation and may show 0 even when untagged issues exist. An accurate untagged count requires a future backend update.
</Note>

### Tasks

<div>
  <img />
</div>

The *Tasks* tab of the *Analytics* dashboard provides a detailed overview of task throughput, stage efficiency, and task timers. It can help answer questions such as:

1. **How productive was each collaborator in terms of labeling and reviewing tasks over the last week?**
   * By filtering the data by *Collaborators* and *Date time range*, you can see how many tasks each team member worked on and how much time they spent on labeling and reviewing.

2. **Which Dataset has the most labels added, edited, or deleted in a given Workflow stage?**
   * You can filter by *Datasets* and *Workflow stage* to see which Dataset is being worked on the most and how many labels are being modified at each stage of the process.

The following charts are visible in the Tasks view:

| **Chart**        | **Description**                                                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Task actions     | Displays the number of annotation tasks submitted, skipped, review tasks approved, and review tasks rejected over a selected date range. |
| Time spent       | Shows the total time spent actively working in the Label Editor, providing insights into productivity.                                   |
| Task performance | Shows the actions taken for all tasks in the Project.                                                                                    |

The **Task performance** table includes the following columns:

* **File name**: The name of the file associated with the task.
* **Data type**: The type of file used in the task (example: image, video, DICOM).
* **Dataset**: The Dataset from which the task originates.
* **Total time**: The total time spent on the task.
* **Total created labels**: The number of labels created in the task.
* **Total edited labels**: The number of labels that were modified in the task.
* **Total deleted labels**: The number of labels that were removed in the task.
* **Time spent** - The amount of time spent in a specific Workflow stage.
* **Collaborators**	- The users who contributed to a specific Workflow stage.
* **Created labels** - The number of labels created in a specific Workflow stage.
* **Edited labels** - The number of labels modified in a specific Workflow stage. In review stages, this refers to [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
* **Deleted labels** - The number of labels removed in a specific Workflow stage.

### Labels

<div>
  <img />
</div>

<Warning>
  Label analytics are not supported for Text and Audio modalities.
</Warning>

The *Labels* tab in the *Analytics* dashboard provides a detailed overview of your team's labeling, reviewing, and task productivity, including time spent. It can help answer questions such as:

1. **How many labels were submitted, approved, or rejected by the team over a given period?**
   * Use the *Label actions* chart and apply the *Date time range* filter to view the total number of labels submitted, approved, or rejected within the selected time frame.

2. **What actions have been taken for specific objects and classifications in the Ontology?**
   * Refer to the *Objects and classifications actions* chart and expand classifications within the Ontology column to see detailed statistics for each classification answer.

3. **How does the team's productivity in labeling compare across different objects or classifications? Do certain objects take more time to label than others?**

   * Analyze the Created, Approved, and Rejected columns in the *Objects and classifications actions* table to identify objects or classifications that might require additional review or clarification using their *Rejection rate*.
   * Compare the average time spent per object or classification by utilizing time-tracking metrics alongside these productivity statistics.

<Tip> All charts allow you to view instance labels or frame labels by selecting the appropriate option from the dropdown next to the filter button. </Tip>

| **Chart**                           | **Description**                                                              |
| ----------------------------------- | ---------------------------------------------------------------------------- |
| Label actions                       | Displays the number of labels submitted, approved, or rejected.              |
| Objects and classifications actions | Shows the actions taken for all objects and classifications in the Ontology. |

The **Objects and classifications actions** table includes the following columns:

* **Ontology**: Represents the Ontology class, encompassing both objects and classifications. For classifications, you can expand to view statistics for each classification answer.
* **Created**: Displays the total number of instances created for this Ontology class. Each instance is counted only once, ensuring that resubmissions of the same label are not double-counted.
* **Approved**: Displays the total number of instances of this Ontology class that have been approved. Approvals are counted multiple times if a label is approved in multiple review stages or if the task is reopened and reviewed again. Use stage-specific filters to see approvals per review stage.
* **Rejected**: Displays the number of instances of this Ontology class that have been rejected. Rejections are double-counted if a label is rejected in multiple review stages, rejected again within the same stage, or if the task is reopened and rejected again. Use stage-specific filters to see rejections per review stage.
* **Rejection Rate**: Calculates the rejection rate percentage of the given Ontology class by dividing the number of rejected labels by the total number of reviewed labels.

### Collaborators

<div>
  <img />
</div>

The *Collaborators* in the *Analytics* dashboard provides a detailed view of time spent annotating and reviewing by Project collaborators. It can help answer questions such as:

1. **How much time did each collaborator spend on annotation / review tasks?**
   * Use the *Time spent* chart to see the time distribution for each collaborator across annotation and review tasks. The *Annotators* and *Reviewers* tables, which provide total and average times for each collaborator.
2. **Which collaborator spent the most time annotating or reviewing tasks in the Project?**
   * Analyze the *Time spent chart* to identify the collaborator with the highest time allocation.

| **Chart**  | **Description**                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| Time spent | Displays the distribution of time spent per collaborator per day                                        |
| Annotators | Table view of all relevant task/label actions and timers for each collaborator in the Annotation stages |
| Reviewers  | Table view of all relevant task/label actions and timers for each collaborator in the Review stages     |

<Info>
  * Labels refer to objects and classifications.
  * Approve actions are double counted if there are multiple review stages.
  * Review actions are double counted if multiple review stages are present or tasks get rejected again in the same review stage.
</Info>

<Note>
  Both tables and all CSV exports are filter-sensitive; they only display information within the selected filter conditions.
</Note>

The **Annotators** and **Reviewers** table columns vary depending on whether the *Instance labels* or *Frame labels* view is selected. They include the following columns.

<AccordionGroup>
  <Accordion title="Instance Labels">
    The **Annotators** table includes the following columns:

    * **Submitted tasks**: Total tasks submitted by the annotator.
    * **Skipped tasks**: Total tasks skipped by the annotator.
    * **Approved tasks**: Tasks submitted by the annotator that were approved in subsequent review stages.
    * **Rejected tasks**: Tasks submitted by the annotator that were rejected during review.
    * **Task rejection rate**: Percentage of the annotator's submitted tasks that were rejected. If multiple review stages are present, use workflow filters to view stage-specific rejections.
    * **Created labels**: Total new labels submitted by the annotator. Include any pre-labels imported using the SDK by admins.
    * **Edited labels**: Total existing labels edited by the annotator. This includes pre-labels from an Agent stage, or labels from a previous Annotate stage. Vertex / coordinate changes are not tracked.
    * **Deleted labels**: Total existing labels deleted by the annotator. This includes pre-labels from an Agent stage, or labels from a previous Annotate stage.
    * **Approved labels**: Labels submitted by the annotator that were approved during review.
    * **Rejected labels**: Labels submitted by the annotator that were rejected during review.
    * **Label rejection rate**: Percentage of the annotator's submitted labels that were rejected during review.
    * **Total annotation time**: Total active time spent annotating in the Label Editor, rounded to the nearest second.
    * **Avg time per task**: Average time spent on each submitted annotation task. Calculated using the total active time spent in the Annotate stage divided by the number of submitted tasks.
    * **Issue actions against user**: The number of [Issue](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#issues-and-comments) actions taken against the user.

    The **Reviewers** table includes the following columns:

    * **Approved tasks**: Number of tasks approved by the reviewer.
    * **Rejected tasks**: Number of tasks rejected by the reviewer.
    * **Task rejection rate**: Percentage of reviewed tasks that were rejected by the reviewer.
    * **Created labels**: Total labels created by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Edited labels**: Total labels edited by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Deleted labels**: Total labels deleted by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Approved labels**: Number of labels approved by the reviewer.
    * **Rejected labels**: Number of labels rejected by the reviewer.
    * **Total review time**: Total active time spent reviewing in the Label Editor, rounded to the nearest second.
    * **Avg time per label**: Average time spent on each reviewed label. Calculated using the total active time spent in the Review stage divided by the number of reviewed labels.
    * **Avg time per task**: Average time spent on each actioned review task. Calculated using the total active time spent in the Review stage divided by the number of actioned reviews.
    * **Issue actions by user**: The number of [Issue](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#issues-and-comments) actions taken by the user.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Frame Labels">
    The **Annotators** table includes the following columns:

    * **Submitted tasks**: Total tasks submitted by the annotator.
    * **Skipped tasks**: Total tasks skipped by the annotator.
    * **Approved tasks**: Tasks submitted by the annotator that were approved in subsequent review stages.
    * **Rejected tasks**: Tasks submitted by the annotator that were rejected during review.
    * **Task rejection rate**: Percentage of the annotator's submitted tasks that were rejected. If multiple review stages are present, use workflow filters to view stage-specific rejections.
    * **Created frame labels**: Total new labels submitted by the annotator. Include any pre-labels imported using the SDK by admins.
    * **Edited frame labels**: Total existing labels edited by the annotator. This includes pre-labels from an Agent stage, or labels from a previous Annotate stage. Vertex / coordinate changes are not tracked.
    * **Deleted frame labels**: Total existing labels deleted by the annotator. This includes pre-labels from an Agent stage, or labels from a previous Annotate stage.
    * **Approved frame labels**: Labels submitted by the annotator that were approved during review.
    * **Rejected frame labels**: Labels submitted by the annotator that were rejected during review.
    * **Frame label rejection rate**: Percentage of the annotator's submitted labels that were rejected during review.
    * **Total annotation time**: Total active time spent annotating in the Label Editor, rounded to the nearest second.
    * **Avg time per task**: Average time spent on each submitted annotation task. Calculated using the total active time spent in the Annotate stage divided by the number of submitted tasks.

    The **Reviewers** table includes the following columns:

    * **Approved tasks**: Number of tasks approved by the reviewer.
    * **Rejected tasks**: Number of tasks rejected by the reviewer.
    * **Task rejection rate**: Percentage of reviewed tasks that were rejected by the reviewer.
    * **Created frame labels**: Total labels created by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Edited frame labels**: Total labels edited by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Deleted labels**: Total labels deleted by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Approved frame labels**: Number of labels approved by the reviewer.
    * **Rejected frame labels**: Number of labels rejected by the reviewer.
    * **Total review time**: Total active time spent reviewing in the Label Editor, rounded to the nearest second.
    * **Avg time per frame label**: Average time spent on each reviewed label. Calculated using the total active time spent in the Review stage divided by the number of reviewed frame labels.
    * **Avg time per task**: Average time spent on each actioned review task. Calculated using the total active time spent in the Review stage divided by the number of actioned reviews.
  </Accordion>
</AccordionGroup>

You can choose which columns should be displayed and included in the CSV export using the *Columns* selector.

<div>
  <img />
</div>

### Issues

The *Issues* tab in the *Analytics* dashboard provides a detailed view of all [issues](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments) created in the Project.

<div>
  <img />
</div>

| **Chart**                     | **Description**                                                              |
| ----------------------------- | ---------------------------------------------------------------------------- |
| Issue actions                 | Shows the number of issues created, resolved, and opened.                    |
| Issue tag occurrence          | Shows the count of all issue tags used within the chosen timeframe.          |
| Issue tag occurrence by class | Shows the actions taken for all objects and classifications in the Ontology. |

The **Issue actions** chart shows the following:

* **Total issues created**: The total number of issues created.
* **Total issues resolved**: The number of issues marked as resolved.
* **Total issues reopened**: The number of issues that were reopened.

**Example - How to Understand Issue Analytics**:

If your **Issue actions** chart shows:

* Total issues created = 19
* Total issues resolved = 20
* Total issues reopened = 2

This means that:

* 19 issues were created.
* All 19 issues were resolved.
* 2 resolved issues were reopened. (This includes manually reopening an issue and re-rejections of labels)
* 1 of the reopened issues was resolved.
* There is one remaining open issue.

### Agents

The *Agents* tab in the *Analytics* dashboard provides a detailed view of all [Agents](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview) run in the Project.

<div>
  <img />
</div>

***

## Join Projects in your Workspace

Workspace Admins can search for and join any Projects that exist within the Workspace. This includes Projects that contain no collaborators.

1. Navigate to **Projects** in the Encord platform.
2. Select the *All Encord projects* tab.
3. Find the Project you want to join.
4. Click **Join project** to join the Project.

<div>
  <img />
</div>

When a Workspace Admin joins a Project, they are automatically assigned the *Admin* [user role for that Project](/platform-documentation/Annotate/roles-and-permissions#projects).

<Tip>Projects can be filtered by Project owner or [Project tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags).</Tip>

<Tip>See all Projects you belong to by clicking the *Filter by project owner* search bar, and selecting *My projects only*. </Tip>


# Project Analytics
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/annotate-project-analytics



## Overview

### Project Overview Summary Cards

The **Overview** tab of your Project displays a set of summary cards that give you an at-a-glance view of Project health. These cards are hidden for labeling-services-only Projects.

**Top row — stat cards**

A row of three compact stat cards appears above the task-status chart:

| **Card**            | **What it shows**                                                           | **Footer link**                                                                           |
| ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Tasks completed** | Number of completed tasks out of the total, with a Project status selector. | Project status dropdown                                                                   |
| **Time spent**      | Total active time spent in the Label Editor across all collaborators.       | **Show breakdown** — navigates to the **Collaborators** analytics tab.                    |
| **Opened issues**   | Number of currently open (unresolved) issues in the Project.                | **Show tasks** — navigates to the Project queue filtered to tasks with unresolved issues. |

**Task status chart**

The task status bar chart displays the number of tasks at each stage of your Workflow. When no task data is available, the chart displays an empty state illustration with the message "Configure data to see tasks status" instead of a blank chart. Tooltips are also disabled in this state.

**Bottom row — distribution cards**

Below the task-status chart, two cards appear side by side:

* **Class Distribution** — shows the top 5 and bottom 5 Ontology classes by label instance count. The subtitle displays the total number of label instances. Click **Show analytics** to open the **Labels** analytics tab. When no label instances exist yet, the card displays "Instance labels by class will appear here."
* **Top Issue Tags** — shows up to 10 issue tags ranked by frequency, with amber-colored horizontal bars. The subtitle displays the total number of issue tags created. Click **Show analytics** to open the **Issues** analytics tab. When no issue tags are configured or used, the card displays an empty state with a **Setup issue tags** link to your issue-tag settings.

<Note>
  The tag counts on the **Top Issue Tags** card reflect tag-action totals (including re-rejections), not unique issue counts. The **No tag** bucket — representing issues with no tag applied — is an approximation and may show 0 even when untagged issues exist. An accurate untagged count requires a future backend update.
</Note>

### Workflow Mini-Map

Annotation, review, and other queue-type stage nodes in the mini-map are clickable. Clicking a stage node navigates you directly to the **Queue** tab, pre-filtered to that stage.

<Tip>
  A pointer cursor appears when you hover over a clickable stage node, indicating that you can click it to jump to the corresponding queue.
</Tip>

The following node types are not clickable and do not navigate to the Queue:

* **Start**
* **Percentage Router**
* **User Router**

## Analytics

The *Analytics* tab of your Project shows event-based analytics for your Project's tasks, labels, and users. The *Analytics* tab has the following views:

* [**Tasks**](#tasks): View analytics on specific tasks in your Project.
* [**Labels**](#labels): View analytics of labels in your Project.
* [**Collaborators**](#collaborators): View collaborator performance in your Project.
* [**Issues**](#issues): View analytics relating to issues in your Project.
* [**Agents**](#agents): View analytics relating to Agent stages in your Project.

<Tip>
  The **Class Distribution** and **Top Issue Tags** cards on the Project Overview provide quick access to the **Labels** and **Issues** sub-tabs of the Analytics section. Click **Show analytics** on either card to navigate directly to the corresponding detailed view.
</Tip>

<Info>
  The analytics available on the Analytics dashboard vary based on user roles:

  * **Admins and Team Managers** have access to the *Tasks*, *Labels*, and *Collaborators* views, offering a comprehensive overview of team performance.
  * **Annotators**, **Reviewers**, and **Annotator + Reviewer** roles can only view the *Task Actions*, *Time Spent*, and *Label Actions* tables, limited to their individual contributions.
</Info>

<Warning>
  Actions performed in the Label Editor or using the SDK are only tracked on the *Analytics* dashboard if they the tasks are actioned (submitted/rejected/approved).
</Warning>

Project Analytics have the following filters:

| **Filter**             | **Description**                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| **Collaborators**      | Filter by specific Project collaborators.                                                         |
| **Datasets**           | Filter tasks based on the dataset they belong to.                                                 |
| **File name includes** | Filter by file name. Regex is supported, allowing filtering by prefix or infix in the file title. |
| **Event source**       | Filter by the source of the event. Either SDK or UI.                                              |
| **Workflow stage**     | Filter tasks based on their current stage in the Workflow.                                        |
| **Class**              | Filter by Ontology class.                                                                         |

**Top row — stat cards**

A row of three compact stat cards appears above the task-status chart:

| **Card**            | **What it shows**                                                           | **Footer link**                                                                           |
| ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Tasks completed** | Number of completed tasks out of the total, with a Project status selector. | Project status dropdown                                                                   |
| **Time spent**      | Total active time spent in the Label Editor across all collaborators.       | **Show breakdown** — navigates to the **Collaborators** analytics tab.                    |
| **Opened issues**   | Number of currently open (unresolved) issues in the Project.                | **Show tasks** — navigates to the Project queue filtered to tasks with unresolved issues. |

**Bottom row — distribution cards**

Below the task-status chart, two cards appear side by side:

* **Class Distribution** — shows the top 5 and bottom 5 Ontology classes by label instance count. The subtitle displays the total number of label instances. Click **Show analytics** to open the **Labels** analytics tab. When no label instances exist yet, the card displays "Instance labels by class will appear here."
* **Top Issue Tags** — shows up to 10 issue tags ranked by frequency, with amber-colored horizontal bars. The subtitle displays the total number of issue tags created. Click **Show analytics** to open the **Issues** analytics tab. When no issue tags are configured or used, the card displays an empty state with a **Setup issue tags** link to your issue-tag settings.

<Note>
  The tag counts on the **Top Issue Tags** card reflect tag-action totals (including re-rejections), not unique issue counts. The **No tag** bucket — representing issues with no tag applied — is an approximation and may show 0 even when untagged issues exist. An accurate untagged count requires a future backend update.
</Note>

### Tasks

<div>
  <img />
</div>

The *Tasks* tab of the *Analytics* dashboard provides a detailed overview of task throughput, stage efficiency, and task timers. It can help answer questions such as:

1. **How productive was each collaborator in terms of labeling and reviewing tasks over the last week?**
   * By filtering the data by *Collaborators* and *Date time range*, you can see how many tasks each team member worked on and how much time they spent on labeling and reviewing.

2. **Which Dataset has the most labels added, edited, or deleted in a given Workflow stage?**
   * You can filter by *Datasets* and *Workflow stage* to see which Dataset is being worked on the most and how many labels are being modified at each stage of the process.

The following charts are visible in the Tasks view:

| **Chart**        | **Description**                                                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Task actions     | Displays the number of annotation tasks submitted, skipped, review tasks approved, and review tasks rejected over a selected date range. |
| Time spent       | Shows the total time spent actively working in the Label Editor, providing insights into productivity.                                   |
| Task performance | Shows the actions taken for all tasks in the Project.                                                                                    |

The **Task performance** table includes the following columns:

* **File name**: The name of the file associated with the task.
* **Data type**: The type of file used in the task (example: image, video, DICOM).
* **Dataset**: The Dataset from which the task originates.
* **Total time**: The total time spent on the task.
* **Total created labels**: The number of labels created in the task.
* **Total edited labels**: The number of labels that were modified in the task.
* **Total deleted labels**: The number of labels that were removed in the task.
* **Time spent** - The amount of time spent in a specific Workflow stage.
* **Collaborators**	- The users who contributed to a specific Workflow stage.
* **Created labels** - The number of labels created in a specific Workflow stage.
* **Edited labels** - The number of labels modified in a specific Workflow stage. In review stages, this refers to [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
* **Deleted labels** - The number of labels removed in a specific Workflow stage.

### Labels

<div>
  <img />
</div>

<Warning>
  Label analytics are not supported for Text and Audio modalities.
</Warning>

The *Labels* tab in the *Analytics* dashboard provides a detailed overview of your team's labeling, reviewing, and task productivity, including time spent. It can help answer questions such as:

1. **How many labels were submitted, approved, or rejected by the team over a given period?**
   * Use the *Label actions* chart and apply the *Date time range* filter to view the total number of labels submitted, approved, or rejected within the selected time frame.

2. **What actions have been taken for specific objects and classifications in the Ontology?**
   * Refer to the *Objects and classifications actions* chart and expand classifications within the Ontology column to see detailed statistics for each classification answer.

3. **How does the team's productivity in labeling compare across different objects or classifications? Do certain objects take more time to label than others?**

   * Analyze the Created, Approved, and Rejected columns in the *Objects and classifications actions* table to identify objects or classifications that might require additional review or clarification using their *Rejection rate*.
   * Compare the average time spent per object or classification by utilizing time-tracking metrics alongside these productivity statistics.

<Tip> All charts allow you to view instance labels or frame labels by selecting the appropriate option from the dropdown next to the filter button. </Tip>

| **Chart**                           | **Description**                                                              |
| ----------------------------------- | ---------------------------------------------------------------------------- |
| Label actions                       | Displays the number of labels submitted, approved, or rejected.              |
| Objects and classifications actions | Shows the actions taken for all objects and classifications in the Ontology. |

The **Objects and classifications actions** table includes the following columns:

* **Ontology**: Represents the Ontology class, encompassing both objects and classifications. For classifications, you can expand to view statistics for each classification answer.
* **Created**: Displays the total number of instances created for this Ontology class. Each instance is counted only once, ensuring that resubmissions of the same label are not double-counted.
* **Approved**: Displays the total number of instances of this Ontology class that have been approved. Approvals are counted multiple times if a label is approved in multiple review stages or if the task is reopened and reviewed again. Use stage-specific filters to see approvals per review stage.
* **Rejected**: Displays the number of instances of this Ontology class that have been rejected. Rejections are double-counted if a label is rejected in multiple review stages, rejected again within the same stage, or if the task is reopened and rejected again. Use stage-specific filters to see rejections per review stage.
* **Rejection Rate**: Calculates the rejection rate percentage of the given Ontology class by dividing the number of rejected labels by the total number of reviewed labels.

### Collaborators

<div>
  <img />
</div>

The *Collaborators* in the *Analytics* dashboard provides a detailed view of time spent annotating and reviewing by Project collaborators. It can help answer questions such as:

1. **How much time did each collaborator spend on annotation / review tasks?**
   * Use the *Time spent* chart to see the time distribution for each collaborator across annotation and review tasks. The *Annotators* and *Reviewers* tables, which provide total and average times for each collaborator.
2. **Which collaborator spent the most time annotating or reviewing tasks in the Project?**
   * Analyze the *Time spent chart* to identify the collaborator with the highest time allocation.

| **Chart**  | **Description**                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| Time spent | Displays the distribution of time spent per collaborator per day                                        |
| Annotators | Table view of all relevant task/label actions and timers for each collaborator in the Annotation stages |
| Reviewers  | Table view of all relevant task/label actions and timers for each collaborator in the Review stages     |

<Info>
  * Labels refer to objects and classifications.
  * Approve actions are double counted if there are multiple review stages.
  * Review actions are double counted if multiple review stages are present or tasks get rejected again in the same review stage.
</Info>

<Note>
  Both tables and all CSV exports are filter-sensitive; they only display information within the selected filter conditions.
</Note>

The **Annotators** and **Reviewers** table columns vary depending on whether the *Instance labels* or *Frame labels* view is selected. They include the following columns.

<AccordionGroup>
  <Accordion title="Instance Labels">
    The **Annotators** table includes the following columns:

    * **Submitted tasks**: Total tasks submitted by the annotator.
    * **Skipped tasks**: Total tasks skipped by the annotator.
    * **Approved tasks**: Tasks submitted by the annotator that were approved in subsequent review stages.
    * **Rejected tasks**: Tasks submitted by the annotator that were rejected during review.
    * **Task rejection rate**: Percentage of the annotator's submitted tasks that were rejected. If multiple review stages are present, use workflow filters to view stage-specific rejections.
    * **Created labels**: Total new labels submitted by the annotator. Include any pre-labels imported using the SDK by admins.
    * **Edited labels**: Total existing labels edited by the annotator. This includes pre-labels from an Agent stage, or labels from a previous Annotate stage. Vertex / coordinate changes are not tracked.
    * **Deleted labels**: Total existing labels deleted by the annotator. This includes pre-labels from an Agent stage, or labels from a previous Annotate stage.
    * **Approved labels**: Labels submitted by the annotator that were approved during review.
    * **Rejected labels**: Labels submitted by the annotator that were rejected during review.
    * **Label rejection rate**: Percentage of the annotator's submitted labels that were rejected during review.
    * **Total annotation time**: Total active time spent annotating in the Label Editor, rounded to the nearest second.
    * **Avg time per task**: Average time spent on each submitted annotation task. Calculated using the total active time spent in the Annotate stage divided by the number of submitted tasks.
    * **Issue actions against user**: The number of [Issue](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#issues-and-comments) actions taken against the user.

    The **Reviewers** table includes the following columns:

    * **Approved tasks**: Number of tasks approved by the reviewer.
    * **Rejected tasks**: Number of tasks rejected by the reviewer.
    * **Task rejection rate**: Percentage of reviewed tasks that were rejected by the reviewer.
    * **Created labels**: Total labels created by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Edited labels**: Total labels edited by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Deleted labels**: Total labels deleted by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Approved labels**: Number of labels approved by the reviewer.
    * **Rejected labels**: Number of labels rejected by the reviewer.
    * **Total review time**: Total active time spent reviewing in the Label Editor, rounded to the nearest second.
    * **Avg time per label**: Average time spent on each reviewed label. Calculated using the total active time spent in the Review stage divided by the number of reviewed labels.
    * **Avg time per task**: Average time spent on each actioned review task. Calculated using the total active time spent in the Review stage divided by the number of actioned reviews.
    * **Issue actions by user**: The number of [Issue](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#issues-and-comments) actions taken by the user.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Frame Labels">
    The **Annotators** table includes the following columns:

    * **Submitted tasks**: Total tasks submitted by the annotator.
    * **Skipped tasks**: Total tasks skipped by the annotator.
    * **Approved tasks**: Tasks submitted by the annotator that were approved in subsequent review stages.
    * **Rejected tasks**: Tasks submitted by the annotator that were rejected during review.
    * **Task rejection rate**: Percentage of the annotator's submitted tasks that were rejected. If multiple review stages are present, use workflow filters to view stage-specific rejections.
    * **Created frame labels**: Total new labels submitted by the annotator. Include any pre-labels imported using the SDK by admins.
    * **Edited frame labels**: Total existing labels edited by the annotator. This includes pre-labels from an Agent stage, or labels from a previous Annotate stage. Vertex / coordinate changes are not tracked.
    * **Deleted frame labels**: Total existing labels deleted by the annotator. This includes pre-labels from an Agent stage, or labels from a previous Annotate stage.
    * **Approved frame labels**: Labels submitted by the annotator that were approved during review.
    * **Rejected frame labels**: Labels submitted by the annotator that were rejected during review.
    * **Frame label rejection rate**: Percentage of the annotator's submitted labels that were rejected during review.
    * **Total annotation time**: Total active time spent annotating in the Label Editor, rounded to the nearest second.
    * **Avg time per task**: Average time spent on each submitted annotation task. Calculated using the total active time spent in the Annotate stage divided by the number of submitted tasks.

    The **Reviewers** table includes the following columns:

    * **Approved tasks**: Number of tasks approved by the reviewer.
    * **Rejected tasks**: Number of tasks rejected by the reviewer.
    * **Task rejection rate**: Percentage of reviewed tasks that were rejected by the reviewer.
    * **Created frame labels**: Total labels created by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Edited frame labels**: Total labels edited by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Deleted labels**: Total labels deleted by the reviewer using [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review).
    * **Approved frame labels**: Number of labels approved by the reviewer.
    * **Rejected frame labels**: Number of labels rejected by the reviewer.
    * **Total review time**: Total active time spent reviewing in the Label Editor, rounded to the nearest second.
    * **Avg time per frame label**: Average time spent on each reviewed label. Calculated using the total active time spent in the Review stage divided by the number of reviewed frame labels.
    * **Avg time per task**: Average time spent on each actioned review task. Calculated using the total active time spent in the Review stage divided by the number of actioned reviews.
  </Accordion>
</AccordionGroup>

You can choose which columns should be displayed and included in the CSV export using the *Columns* selector.

<div>
  <img />
</div>

### Issues

The *Issues* tab in the *Analytics* dashboard provides a detailed view of all [issues](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments) created in the Project.

<div>
  <img />
</div>

| **Chart**                     | **Description**                                                              |
| ----------------------------- | ---------------------------------------------------------------------------- |
| Issue actions                 | Shows the number of issues created, resolved, and opened.                    |
| Issue tag occurrence          | Shows the count of all issue tags used within the chosen timeframe.          |
| Issue tag occurrence by class | Shows the actions taken for all objects and classifications in the Ontology. |

The **Issue actions** chart shows the following:

* **Total issues created**: The total number of issues created.
* **Total issues resolved**: The number of issues marked as resolved.
* **Total issues reopened**: The number of issues that were reopened.

**Example - How to Understand Issue Analytics**:

If your **Issue actions** chart shows:

* Total issues created = 19
* Total issues resolved = 20
* Total issues reopened = 2

This means that:

* 19 issues were created.
* All 19 issues were resolved.
* 2 resolved issues were reopened. (This includes manually reopening an issue and re-rejections of labels)
* 1 of the reopened issues was resolved.
* There is one remaining open issue.

### Agents

The *Agents* tab in the *Analytics* dashboard provides a detailed view of all [Agents](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview) run in the Project.

<div>
  <img />
</div>

***

### Analytics FAQ

**How do I track annotator performance on pre-labeling/model labels?** \
Annotator performance on pre-labeled or model-generated labels can be tracked using the *Edited Labels* and *Deleted Labels* metrics in the *Annotators* table. These include:

* Labels that were pre-labeled using an Agent stage.
* Labels that were modified by annotators during the annotation process.

Vertex/coordinate changes are not tracked as edits.

***

**Can I export analytics for payroll or performance tracking?** \
Yes, CSV exports from the *Analytics* tab provide data that can be used for payroll or performance tracking.

* The *Annotators* and *Reviewers* tables contain total time spent, tasks submitted, approved, and rejected.
* Data in exports is filter-sensitive, so you can apply filters before exporting.
* Review time is rounded to the nearest second per task.

***

**What is counted as a created label?**  \
A created label is any new label added by an annotator or reviewer. This includes:

* A completely new label drawn or added during annotation.
* Labels created in [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review) mode.
* Labels submitted using the SDK (counted under the annotator who submitted the task).

***

**What is counted as an edited label?**  \
An edited label is a modification made to an existing label. This includes:

* Changes to attributes or classifications.
* Labels modified from pre-labeling or a previous annotation stage.

<Note>Changes to vertices/coordinates alone **do not** count as an edit.</Note>

***

**Can I customize what data is included in the CSV exports?** \
No, CSV exports are pre-defined and contain all available metrics. However, you can **filter the data** before exporting to limit what is included.

***

**How are timers tracked?** \
Timers track *active time* spent in the Label Editor:

* Time is rounded to the nearest second per task.
* Pauses or inactivity do not count toward the active time.
* The `Avg time per task` metric is calculated by dividing the total annotation/review time by the number of submitted tasks.

***

**Are label events counted if a task is skipped?** \
No. If a task is skipped, any actions performed before skipping (for example, creating/editing labels) are not recorded in the Analytics dashboard.

***

**How are actions outside of the task queue counted?**  \
Actions performed outside of the task queue, such as label modifications using the SDK are only tracked if the task is subsequently submitted, rejected, or approved.

***

**How does the SDK filter work?**  \
The *Event Source* filter allows you to view actions performed using the SDK or UI.

***

**What happens if someone is inactive or takes a break?**

* Inactive time is not recorded. The system only tracks time when the annotator is actively working in the Label Editor.
* If an annotator takes a break without closing the task, their session remains open, but inactive time is not counted.

***

**How long does it take for actions to appear on the Analytics dashboard?**

* It takes a maximum of 5 minutes for any action to appear on the Analytics dashboard.

***

**What summary cards appear on the Project Overview tab?** \
The Project **Overview** tab displays a set of summary cards that give you a quick snapshot of Project health:

* **Tasks completed** — shows the number of completed tasks out of the total, with a Project status selector in the footer.
* **Time spent** — shows the total active time spent in the Label Editor across all collaborators. Click **Show breakdown** to go directly to the **Collaborators** tab in Analytics.
* **Opened issues** — shows the number of currently open issues. Click **Show tasks** to open the task queue filtered to tasks with unresolved issues.

These three stat cards appear in a row above the **Project task status** chart. Below the chart, the **Class distribution** and **Top issue tags** cards appear side by side.

<Note>All stat cards and the Class distribution and Top issue tags cards are hidden for labeling-services-only Projects.</Note>

***

**How do the Class Distribution and Top Issue Tags cards on the Project Overview relate to the Analytics tab?** \
The **Class distribution** and **Top issue tags** cards on the Project **Overview** tab display summary analytics drawn from the same data as the full Analytics tab. Each card includes a **Show analytics** link that takes you directly to the corresponding sub-tab. Encord hides the **Show analytics** link when a card has no data to display.

* The **Class distribution** card links to the **Labels** sub-tab, where you can explore per-class label counts, approval rates, and rejection rates in detail. The card shows the top 5 and bottom 5 classes by label count. The subtitle displays the total number of label instances.
* The **Top issue tags** card links to the **Issues** sub-tab, where you can view issue tag occurrence charts and full issue action history. The card shows up to 10 issue tags ranked by frequency, with amber-colored bars. The subtitle displays the total number of issue tags created.

<Tip>Use the **Show analytics** links on the Overview cards as a quick entry point when a class or issue tag warrants deeper investigation.</Tip>

<Note>Tag bar counts on the **Top issue tags** card reflect tag-action totals (including re-rejections), not unique issue counts. The count for untagged issues is a frontend approximation and may under-report when untagged issues exist.</Note>

***

**What happens when there are no labels or issue tags yet?** \
Each card displays an informational empty state when no data is available:

* The **Class distribution** card displays "Instance labels by class will appear here."
* The **Top issue tags** card displays "Most common issue tags will appear here" and includes a **Setup issue tags** link to the issue tag settings so you can configure tags before annotation begins.
  <Tip>Use the **Open in Analytics →** links on the Overview cards as a quick entry point when a class or issue tag warrants deeper investigation.</Tip>

***

**Can I navigate to a specific Workflow stage queue from the Project Overview?** \
Yes. The Workflow mini-map on the Project **Overview** tab displays your Project's Workflow stages as interactive nodes. Clicking an annotation, review, or other queue-type stage node navigates you directly to the **Queue** tab, pre-filtered to that stage.

* A pointer cursor appears when you hover over a clickable stage node.
* **Start**, **Percentage Router**, and **User Router** nodes are not clickable and do not link to the queue.

<Tip>Use the Workflow mini-map as a quick shortcut to jump directly into a specific stage's queue without manually switching tabs and selecting a stage.</Tip>

***

**What happens to the analytics view when I click Preview on the Task layout card?** \
Clicking **Preview** on the **Task layout** card in the Project Overview left panel replaces the right-panel analytics content — including the task-status chart and stat cards — with an embedded label editor preview. The analytics view returns when you click **Close preview** in the preview panel header.

<Note>The **Preview** button is disabled when the Project has no demo data and no linked datasets. Link at least one dataset to the Project to enable the preview.</Note>

***

**Who can see the Manage and Configure buttons on the Data Overview card?** \
The **Manage** and **Configure** buttons on the **Data Overview** card in the Project Analytics Overview are only visible to Workspace Admins and Project Admins.


# Project Settings
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/annotate-project-settings



## Team

To manage Project collaborators, select the *Team* pane in your project *Settings*. Collaborators can be added individually or as [groups of users](/platform-documentation/General/general-workspace-settings#user-groups).

**To add collaborators to a Project**:

1. Search for the collaborator or the [group](/platform-documentation/General/general-workspace-settings#user-groups) you want to add. Multiple collaborators and groups can be added at once.

<Note>
  You can invite users who are not part of your Workspace. Invitations to join the Workspace are sent to them, and once accepted, they become Project collaborators. See instructions on how to do this [here](/platform-documentation/General/general-workspace-settings#accepting-invites).
</Note>

<Info>
  Only group members are added when a group is assigned to a Project. Group managers are not included.
</Info>

<div>
  <img />
</div>

2. Select a user role.
   * **Annotator**: Can access and label tasks in all or selected Annotate stages in the Project.
   * **Reviewer**: Can access and review tasks in all or selected Review stages in the Project.
   * **Annotator & Reviewer**: Performs both annotation and review tasks.
   * **Team Manager**: Can access and label tasks in all stages in the Project. Can move, assigns, prioritize tasks to users. Can manage Project collaborators.
   * **Admin**: Grants full administrative control over the Project.

3. Click **Add to project**.

<Info>
  To remove a user or group from the Project click the *Delete* icon in the *Unassign* column.

  <div>
    <img />
  </div>
</Info>

<AccordionGroup>
  <Accordion title="How to import collaborators using a CSV">
    1. Click **Actions**.
    2. Select **Import collaborators**.
    3. Add the CSV file containing users and their roles.
    4. Click **Submit**.

    <div>
      <img />
    </div>

    CSV files must be formatted in the following manner:

    ```csv theme={"dark"}
    Email,Role,Group
    david@acme.com,Admin,
    adam@acme.com,Annotator,
    joe@acme.com,Annotator,
    ```
  </Accordion>
</AccordionGroup>

## Options

### Copy Project

To copy a Project:

1. Click the **Copy project** button in the *Options* section of the Project's *Settings*.
2. Select the components of the Project you want to copy into the new Project. The Ontology must be copied and is therefore always selected. All components of the current Project are selected by default.

<Info>
  You can copy any combination of the following assets:

  * **Datasets** – All Datasets are copied.
  * **Labels** – Copies labels in specified data units. By default, all labels are included. To copy only specific labels, select *Selected Labels* from the dropdown. Click **+Advanced settings** to filter labels by status.
  * **Models** – Copies all models in the Project, including their training logs.
  * **Collaborators** – Copies all Project users along with their roles. Project admins are always included.

  <div>
    <img />
  </div>
</Info>

3. Click the **Make a copy** button to copy the Project with the specified components.

***

### Upload Annotation Instructions

1. Navigate to the *Settings* tab of your Project.

2. Click the **Upload file** button to upload instructions for your annotators. Both PDF and video files are supported (`.mp4`, `.webm`, `.mov`, `.avi`, `.mkv`).

<div>
  <img />
</div>

<Tip>
  To ensure the best possible results, provide as much detail as possible about what you would like annotated and how precise bounding boxes should be drawn. For example, instead of saying 'person', consider defining what should constitute a person for your annotators - only a full person? A torso? Or should any part of a person in a frame be labeled as a 'person'? The more specific your annotator instructions, the higher the chances that your annotators perform well.
</Tip>

<Note>
  Once uploaded, annotation instructions are accessible within the Label Editor, and the Workflow tab of your Project. PDF instructions are displayed as an embedded document, while video instructions play automatically in the Label Editor.

  <div>
    <img />
  </div>
</Note>

***

### Project Tags

<Note>Project tags are created and managed on the [Workspace level](/platform-documentation/General/general-workspace-settings#project-tags-tab). Once created for the Workspace they can be added to individual Projects.</Note>

Project tags allow you to:

* Flexibly categorize and group your Projects.
* Filter your list of Projects by tag.

**To add or remove Project tags**:

1. Navigate to the Settings tab in a Project and click the *Project tags* drop-down.
   All available tags in your Workspace are shown.
2. Click on a tag to add it to a Project.

<Tip>
  Remove a tag from your Project by clicking the same tag again, or clicking the **x** button next to its name.
</Tip>

<div>
  <img />
</div>

<Tip>
  You can also edit Project tags directly from the Project Overview page. Hover over the **Project tags** card to reveal the **Edit** button, then click it to add or remove tags inline.
</Tip>

<Note>
  The **Edit** button on the Project tags card is only visible to users with tag-edit permissions, and only for Projects associated with a Workspace. Projects created before Workspace membership do not support this feature.
</Note>

***

### Issue Tags

<Note>Issue tags can be created and managed on the [Workspace level](/platform-documentation/General/general-workspace-settings#issue-tags-tab) by Workspace admins, or on the Project level by Project admins.</Note>

<Tip>
  A complete walkthrough of all things Issues and Comments related can be found [here](/end-to-end/Features/issues-e2e).
</Tip>

Issue tags allow you to:

* Flexibly categorize and group your [issues](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#comments-and-issues) within Projects.
* Get [insights on issues](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#issues) being created by collaborators.

**To add or remove Issue tags from Projects**:

1. Navigate to the Settings tab for a Project and click the *Issue tags* drop-down.
   All available tags in your Workspace are shown.
2. Click on a tag to add it to the Project.
3. (Optionally) Create a new tag by typing the name of the tag and hitting <kbd>ENTER</kbd>.

<Tip>
  Remove an issue tag from your Project by clicking the same tag again, or clicking the **x** button next to its name.
</Tip>

***

### Ontology Settings

You can view or switch the Ontology attached to your Project.

<Note>Changing the Ontology can render existing labels invalid and lead to data inconsistency.</Note>

* Click the **Switch ontology** button to switch the Ontology linked to your Project. The resulting pop-up allows you to choose an existing Ontology from a list, or [create a new Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies) for this Project.

* Click the **View ontology** button to view the details of the Ontology that is attached to the current Project.

<Tip>
  When an Ontology is already configured, the Project Overview page displays an **Edit** button directly on the Ontology card. Hover over the card to reveal the button, then click it to open the Ontology editor without navigating to Settings.
</Tip>

#### Make classifications read only

To prevent annotators from adding or changing specific classifications:

1. Navigate to the **Settings** tab of your Project.
2. In **Ontology settings**, open the **Read only classifications** dropdown.
3. Select one or more classifications. To make a classification editable again, remove it from the selection.

In annotation stages, annotators can view selected classifications and their existing answers, but cannot add, edit, delete, change their ranges, or paste copied ranges. Mixed bulk operations skip read-only classifications and apply only to editable items. This restriction includes all attributes nested under a selected classification. Read-only classifications are marked **Read only** in the Label Editor. The setting does not restrict classification editing in review stages.

***

### Preload Next Task

<div>
  <img />
</div>

Turning on the `Enable task media preloading` feature preloads the next task in the background while the user is working in the Label Editor. This reduces wait times for the next task after submitting a task. This setting is disabled by default.

When enabled, the preloaded task is automatically assigned to the user, preventing others from initiating it.

<Info>
  * This feature is supported for single images and videos.
  * Only the media file is preloaded. Labels are not preloaded.
</Info>

***

### Hide Annotator Usernames

Enable this setting to hide annotator usernames and emails during consensus review. When enabled, annotator identities are replaced with "Hidden user" labels and anonymous avatars throughout the Label Editor.

**To enable or disable this setting**:

1. Navigate to the *Settings* tab of your Project.
2. In the **General** section, toggle the **Hide annotator usernames** switch.

<Info>
  This setting only affects the display of annotator identities in consensus review mode. It does not impact task assignment, project permissions, or other functionality.
</Info>

<Note>
  When this setting is enabled, all annotator-specific visual elements (usernames, emails, avatar colors) are anonymized to maintain reviewer objectivity during consensus evaluation.
</Note>

***

## Manage Datasets Attached to a Project

### Change Dataset

The *Datasets* section of the *Options* pane shows all the Datasets attached to a Project.

<div>
  <img />
</div>

### Add or Remove a Dataset

<Steps>
  <Step title="Open the Project Data Management modal">
    Navigate to the **Settings** tab of your Project and open the **Project Data Management** modal.
  </Step>

  <Step title="Select a Dataset">
    In the left panel, select **Datasets** from the dropdown, then select the Dataset you want to add or remove. The center panel displays a thumbnail preview of the Dataset's files.
  </Step>

  <Step title="Add or remove the Dataset">
    * To add the Dataset, click **Add dataset** in the center panel.
    * To remove an already-attached Dataset, click **Remove dataset** in the center panel. Encord displays a confirmation prompt before removing the Dataset.

    <Info>
      The default Dataset for a Project cannot be removed and shows an **DEFAULT** badge.
    </Info>

    <Info>
      If a Dataset has a backing storage folder (a live Dataset), the **Project data** panel displays a **LIVE** indicator. New files added to the source folder automatically appear in the Project.
    </Info>
  </Step>
</Steps>

### Add or Configure a Folder

<Steps>
  <Step title="Open the Project Data Management modal">
    Navigate to the **Settings** tab of your Project and open the **Project Data Management** modal.
  </Step>

  <Step title="Select a folder">
    In the left panel, select **Folders** from the dropdown, then select the folder you want to add. The center panel displays the folder's contents.
  </Step>

  <Step title="Select files">
    Choose which files to include:

    * Click **Select all** to include every file currently in the folder.
    * Select individual files to include only a specific subset.
  </Step>

  <Step title="Configure Continuous Data Flow (optional)">
    Toggle **Continuous data flow** to control whether future files added to the folder automatically enter the Project.

    <Info>
      **Continuous Data Flow** is only available when all items in the folder are selected. The toggle is disabled when only a subset of items is selected.
    </Info>

    When Continuous Data Flow is on, the behavior depends on whether you have also applied filters:

    * **No filters** — All new files added to the folder automatically appear in the Project.
    * **With filters** — New files pass through the configured filters before entering the Project.
  </Step>

  <Step title="Apply filters (optional)">
    Use the filter options in the center panel to narrow which files from the folder are included in the Project.
  </Step>

  <Step title="Add or update the folder">
    * To add the folder to the Project for the first time, click **Add folder**.
    * To save changes to an already-added folder (file selection, filters, or Continuous Data Flow settings), click **Update**.
    * To remove the folder from the Project, click **Remove folder**.
  </Step>
</Steps>

***

## Project Explorer Configuration

<Warning>
  All collections and embeddings are lost when reconfiguring the project explorer. This action cannot be undone.
</Warning>

You can reconfigure the explorer settings to adjust how your data is processed and analyzed in your Projects.

**To reconfigure project explorer settings**:

1. Navigate to the *Settings* tab of your Project.
2. In the **Project Explorer Configuration** section, click **Configure**.
3. In the configuration modal, adjust the following settings as needed:
   * **Video Sampling Rate**: Set the frame sampling rate for video files
   * **Custom Embedding Key**: Specify a custom key for embeddings computation
   * **Compute Embeddings**: Enable or disable embeddings computation
   * **Compute Advanced Metrics**: Enable or disable advanced metrics computation
4. Click **Configure** to apply the new settings.

<Info>
  The reconfiguration process re-imports your Project data with the new settings. This may take some time depending on the size of your Project.
</Info>

***

## Task Rules

<div>
  <img />
</div>

The **Task rules** section on the Project Overview tab summarizes the Project's label validation rules. Admins and Team Managers can click **Add task rules** to open **Manage rules**, where they can add, edit, or remove rules. Coverage and overlap rules apply to the whole task. You can configure minimum cuboid point-count rules for the whole task or individual cuboid Ontology classes.

<Note>
  Rules only appear in Projects that contain bounding boxes, rotatable bounding boxes, cuboids, segmentations, or bitmasks.
</Note>

Each role has the following enforcement levels:

* **Warning**: The Label Editor flags violations, but annotators can still submit the task.
* **Blocking**: Annotators cannot submit the task until they resolve all violations. The **Submit** button is greyed out, and hovering over it identifies the blocking rules.

| Rule                                  | Applies To                           | Description                                                                                                                                                                                       | Behavior / Notes                                                                                                                                                                                                                                                                                |
| ------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Required 3D segmentation coverage** | 3D scene (point cloud)               | Sets the minimum percentage of cloud points that must be covered by segmentations before a task can be submitted.                                                                                 | Helps enforce annotation completeness for point cloud segmentation tasks.                                                                                                                                                                                                                       |
| **Required bitmask coverage**         | Image or video tiles                 | Sets the minimum percentage of pixels that must be covered by bitmasks on every frame.                                                                                                            | Set to **0** to disable. Applies frame-by-frame across every frame in a tile.                                                                                                                                                                                                                   |
| **Prevent cuboid overlap**            | 3D scene (cuboids)                   | Warns annotators when cuboids overlap each other in the 3D scene.                                                                                                                                 | Overlaps surface in the rules panel and are highlighted in the editor.                                                                                                                                                                                                                          |
| **Prevent segmentation overlap**      | 3D scene (point cloud segmentations) | Warns annotators when point-cloud segmentations cover the same points within a label space.                                                                                                       | Overlapping pairs surface in the rules panel, grouped by the frames the space is active on.                                                                                                                                                                                                     |
| **Prevent bitmask overlap**           | Image or video tiles                 | Warns annotators when bitmasks cover the same pixels on a frame.                                                                                                                                  | Overlapping pairs surface in the rules panel, with an optional mode that highlights the overlapping regions in red.                                                                                                                                                                             |
| **Minimum points inside cuboid**      | 3D scene (cuboids)                   | Sets the minimum number of sensor points that must fall inside a cuboid.                                                                                                                          | Cuboids below this count are highlighted in the editor. Leave empty to disable.                                                                                                                                                                                                                 |
| **Constant cuboid size**              | 3D scene (cuboids)                   | Requires each cuboid to keep the same size across every frame where it appears. You can apply the rule to all cuboid classes or selected classes and optionally define one or more allowed sizes. | When multiple allowed sizes are configured, press <kbd>Tab</kbd> to cycle through them. Press <kbd>R</kbd> or <kbd>T</kbd> to rotate a fixed-size placement preview. The rules panel groups violations by object; use **Fix** to apply the first frame's size or an allowed size to all frames. |

Rule violations and their configured requirements appear in the Label Editor's Issues panel.

<div>
  <img />
</div>

***

## Delete Project

You can delete your Project by going to the *Danger zone* tab of the Project settings.

To delete a Project, click the red **Delete project** button.

![Delete Project](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/delete-project.gif)

<Warning>
  Deleting your Project **does not** delete the Datasets attached to the Project, but it does delete the Project's labels and Ontology.
</Warning>


# Task Queue
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/annotate-workflow-queue



The *Queue* tab in an Encord Annotate Project gives you a centralized view of all tasks across every Workflow stage. Use it to assign tasks to annotators and reviewers, set priorities, apply filters, and start labeling or reviewing work — all without leaving the Project dashboard.

<Note>The order of data units (tasks) with the same priority in the Task Queue is completely random. However, each user sees the same random order of tasks.</Note>

<div>
  <iframe />
</div>

***

## Queue Layout by Role

The *Queue* tab adapts based on the logged-in user's role.

<AccordionGroup>
  <Accordion title="Queue (Admin, Team Manager)">
    ### Queue (Admin, Team Manager)

    <div>
      <img />
    </div>

    * **A** — The list of Workflow stages shows the number of data units currently in each stage. Click a stage to view its task queue.
    * **B** — Shows the task's priority number. Tasks are listed in descending order of priority by default.
    * **C** — Search, sort, and filter the list of data units by *Dataset*, *Assignee*, *Data Type*, *Status*, or *Issue Status*.
    * **D** — Shows the task's Status (New, Reopened, Skipped). For tasks that have moved through previous stages, an info icon appears next to the status badge. Hover over the icon to see details about the previous stage, including the stage name, who performed the action, and when it occurred.
    * **E** — Task Actions. Assign or release selected tasks, adjust priority, or move tasks to a different Workflow stage.
    * **F** — Switch between List and Explorer view.
    * **G** — Use the **Start task** button to begin labeling or reviewing a task.
    * **H** — Click the **Initiate** button to open a specific task in the Label Editor.

    The *Queue* tab lists tasks in the same order they appear in the Label Editor.
  </Accordion>

  <Accordion title="Queue (Annotator)">
    ### Queue (Annotator)

    Annotators only see tasks in the *Annotate* stage that are assigned to them. They cannot view tasks in the Review stage or tasks assigned to other users.
  </Accordion>

  <Accordion title="Queue (Reviewer)">
    ### Queue (Reviewer)

    Reviewers only see tasks in the *Review* stage that are assigned to them. They cannot view tasks in the Annotate stage or tasks assigned to other users.
  </Accordion>

  <Accordion title="Queue (Annotator + Reviewer)">
    ### Queue (Annotator + Reviewer)

    Users with the *Annotator + Reviewer* role can see both the *Annotate* and *Review* tabs in the Queue. They are limited to tasks assigned to them in each respective stage.
  </Accordion>
</AccordionGroup>

***

## Paused Agent Indicator

When any Agent stage in your Workflow is paused, the **Queue** tab displays an information icon next to its name. This indicator alerts you that tasks in paused Agent stages do not execute automatically until the Agents are unpaused.

<Tip>Click the information icon to see which Agent stages are paused and need attention.</Tip>

***

## Agent Stages

When viewing an Agent stage, the Queue displays additional controls and status information for Workflow agents.

**Agent Status Banner**

For Agent stages, a status banner appears above the task list showing the agent name and icon (click to view detailed agent configuration), a status indicator showing whether the agent is Live (green) or Paused (orange), and control buttons that Admins and Team Managers can use to pause/resume agents or view agent settings.

**Agent Controls**

<Note>Only Workspace and Project Admins and Team Managers can control agent execution.</Note>

| Action                | How                                                                    |
| --------------------- | ---------------------------------------------------------------------- |
| Pause agent           | Click **Pause** to stop automatic processing                           |
| Resume agent          | Click **Go live** to resume automatic processing                       |
| Manual task execution | Navigate to paused agent stage → find **Pending** task → click **Run** |
| Retry failed task     | Find **Failed** task → click **Retry**                                 |

<Tip>Use manual execution when testing agent configurations or troubleshooting specific data units before resuming live processing.</Tip>

**Agent Execution Status**

For Projects using Agents in their Workflow, tasks display execution status badges showing the current state of automated processing:

| Status     | Description                                                               |
| ---------- | ------------------------------------------------------------------------- |
| Pending    | The agent execution is queued and waiting to start.                       |
| Dispatched | The agent execution has been assigned to a worker.                        |
| Running    | The agent is currently processing the task.                               |
| Succeeded  | The agent execution completed successfully.                               |
| Failed     | The agent execution encountered an error and failed to complete.          |
| Timed out  | The agent execution exceeded the maximum allowed time and was terminated. |
| Canceled   | The agent execution was manually canceled before completion.              |

**Retry Failed Tasks**

You can retry tasks that failed or timed out by selecting one or more affected tasks in the Queue, then clicking Retry failed to re-run the agent on those tasks. The system will attempt to execute the Agent again on the selected tasks.

<Note>The Retry failed button is only available for Agent stages with catalog agents and only appears when you have selected tasks that failed or timed out.</Note>

**Moving Agent Tasks**

When moving agent tasks to the next stage, the system skips tasks that are currently running or dispatched (they remain in the current stage), only moving tasks that are not actively being processed. A confirmation dialog will show how many tasks are moved and how many are skipped.

<Warning>Tasks that are currently running or dispatched cannot be moved and remain in their current stage until execution completes.</Warning>

***

## Queue View Options

The Queue offers different view modes to help you work with tasks more effectively:

* **List view** — The default tabular view showing tasks in a structured list format
* **Grid view** — A visual grid layout for browsing tasks and labels
* **Visual Queue** — An enhanced visual interface for task management (when available)

Use the view switcher in the top-right corner of the Queue to change between available options.

<div>
  <img />
</div>

<Note>Visual Queue availability varies based on your Project settings and enabled features. Some Projects may only show the List and Grid view options.</Note>

***

## Filters and Sorting

**Filters**

| Filter           | Description                                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Dataset          | Show only data units belonging to the selected Dataset(s).                                                                       |
| Assignees        | Show tasks assigned to a specific user.                                                                                          |
| Last Actioned By | Show tasks last actioned by the selected user.                                                                                   |
| Data Type        | Show data units of a specific type (image, video, audio, etc.).                                                                  |
| Issue Status     | Show tasks with *Resolved* or *Unresolved* issues.                                                                               |
| Object Count     | Filter tasks by the number of labeled objects they contain (when available).                                                     |
| Execution Status | Show agent tasks by their execution status (Pending, Running, Failed, etc.). Available only in Agent stages with catalog agents. |

Click **Assigned to me** (the person icon beside **Filter**) to show only tasks assigned to you. Click it again to clear the Assignee filter. Selecting this shortcut replaces any existing Assignee selection. It is available in stages that support the Assignee filter when you are an assignable Project member.

**Sort by**

Click **Sort by** next to the filter button to sort the queue by:

* Task priority, or alphabetically by data unit name
* Object count (when available)
* Ascending or descending order

The default sort is descending order of task priority.

<Note>Object count filtering and sorting are available based on your organization's feature access.</Note>
<Tip>Use the keyboard shortcut <kbd>S</kbd> to open the sort dropdown, or <kbd>Ctrl</kbd> + <kbd>O</kbd> to quickly toggle between ascending and descending order.</Tip>

***

## Task Status

The task Status indicates what actions have previously been taken on a task. For tasks that have moved through previous Workflow stages, an info icon appears next to the status badge. Hover over the icon to see details about the previous stage, including the stage name, who performed the action, and when it occurred.

| Status   | Description                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------ |
| New      | The task has not been worked on since being added to the Project.                                |
| Reopened | The task was rejected during Review and has been returned for re-labeling.                       |
| Skipped  | The task was skipped by one or more annotators.                                                  |
| Pending  | (Agent stages only) The task is queued for agent processing.                                     |
| Paused   | (Agent stages only) The task is waiting for Agent processing, but the Agent is currently paused. |
| Failed   | (Agent stages only) Agent execution failed and the task needs to be retried.                     |

<Tip>The previous stage information helps you track task history and understand the workflow progression for each data unit.</Tip>

***

## Review Status

In **Review** stages, the queue includes a **Review Status** column that shows each task's current status in the review lifecycle. You can sort by this column and filter on it using the **Review Status** filter to focus on tasks at a particular point in review.

| Review Status | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| New           | The task has entered the Review stage and has not been actioned yet. |
| Assigned      | The task is assigned to a reviewer.                                  |
| Released      | The task was released back to the pool of unassigned review tasks.   |
| Reopened      | The task was rejected in a later step and returned for review again. |
| Skipped       | The task was skipped by one or more reviewers.                       |

<Note>The Review Status column and filter appear only in Review stages. Review tasks reuse the same lifecycle statuses as annotation tasks while they are in the queue.</Note>

***

## Task Actions

### Per-Row Task Actions

Every task row in the Queue has a three-dot (**⋯**) menu that gives you quick access to actions for that individual task without selecting it first.

<Note>**Assign**, **Release**, **Change priority**, and **Move to stage** are only available to Workspace and Project Admins and Team Managers. **View**, **Activity log**, and **API details** are available to all users who can see the queue row.</Note>

The following actions are available from the per-row menu, grouped into sections:

| Action              | Description                                                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **View**            | Opens the task in the Label Editor in view-only mode.                                                                                                                                                                                                   |
| **Assign**          | Opens a submenu listing available project members for the current stage. Select a member to assign the task to them. Available on Annotate and Review stages only. Not available on Consensus Annotation rows, where assignment is managed per subtask. |
| **Release**         | Releases the task from its current assignee. Only appears when the task is assigned.                                                                                                                                                                    |
| **Change priority** | Opens a modal where you can set a new priority value for the task.                                                                                                                                                                                      |
| **Move to stage**   | Displays a submenu of valid target Workflow stages. Select a stage to move the task there immediately. Container stages such as Consensus and Parallelization are excluded from the list of valid targets.                                              |
| **Activity log**    | Opens the activity log for the task.                                                                                                                                                                                                                    |
| **API details**     | Opens the API details panel for the task.                                                                                                                                                                                                               |

<Warning>If any mutating action (Assign, Release, Change priority, or Move to stage) fails, Encord displays an error notification. No changes are applied to the task in that case.</Warning>

### Bulk Task Actions

The **Actions** button lets you perform operations on multiple selected tasks at once. The button appears only after you select one or more tasks:

* **List and Grid views** — The **Actions** button appears inside the floating selection toolbar at the bottom of the screen.
* **Explorer view** — The **Actions** button appears in the top action bar alongside other controls.

The floating selection toolbar displays items in this order: **\[N] selected · Clear · Select all · Actions**.

<Tip>Hover over **Select all** to see a tooltip with the hint that you can hold `Shift` to select a range of tasks.</Tip>

### View a Task

You can open any task from the Queue in view-only mode without assigning it to yourself.

<div>
  <img />
</div>

To edit labels while viewing a task, click **Edit** or use <kbd>Ctrl</kbd> + <kbd>E</kbd>. When finished, click **Save and return to view** to return to view mode.

<Tabs>
  <Tab title="View Mode">
    <div>
      <img />
    </div>
  </Tab>

  <Tab title="Edit Mode">
    <div>
      <img />
    </div>
  </Tab>
</Tabs>

### Assign Tasks

<Note>Only Workspace and Project Admins and Team Managers can assign tasks.</Note>

You can assign tasks in two ways:

* **Per-row** — Click the **⋯** menu on any task row and select **Assign**, then choose a project member from the submenu.
* **Bulk** — Select one or more tasks and use the **Actions** menu to assign them to a specific annotator or reviewer.

Assigned tasks appear in the assignee's personal Queue view.

To release an assignment, use the **⋯** menu on the task row and select **Release**, or select multiple tasks and choose **Release** from the **Actions** menu.

### Move Tasks

<Note>Only Workspace and Project Admins and Team Managers can move tasks.</Note>

<div>
  <img />
</div>

You can move tasks from their current stage directly to any other stage in the Workflow:

* **Per-row** — Click the **⋯** menu on any task row, select **Move to stage**, then choose the target stage from the submenu.
* **Bulk** — Select one or more tasks and use the **Actions** menu to move them to a different stage.

<Warning>
  - Moving tasks skips all intermediate Workflow stages, placing them immediately into the selected stage.
  - All labels (objects and classifications) are automatically approved when tasks move to a COMPLETE stage.
  - Webhooks do not fire when tasks are moved this way.
  - Tasks cannot be moved into Consensus stages.
  - Tasks in a Consensus Annotate block cannot be moved to Consensus Review blocks.
  - The following analytics do not apply to moved tasks: `Labels created`, `Approved labels`, `Rejected labels`.
  - Agent configuration controls are disabled when a Workflow stage has queued tasks. You must move tasks to another stage before changing the agent configuration.
</Warning>

### Set Task Priority

<Note>Only Workspace and Project Admins and Team Managers can set task priority.</Note>

You can set task priority in two ways:

* **Per-row** — Click the **⋯** menu on any task row and select **Change priority**. Enter a new priority value in the modal that appears and confirm.
* **Bulk** — Select tasks in the Queue and use the **Actions** menu to assign a priority number.

Higher priority numbers cause tasks to appear earlier in the queue. Tasks with the same priority are displayed in random order.

***

## Consensus Annotation Subtasks

In a Consensus Annotation stage, each task expands to show individual subtask rows — one per annotator assigned to that consensus group. Each subtask row has its own **Initiate** button.

### Peer Annotation Gating

When the **Show peer annotations** setting is enabled on a Consensus Annotation Workflow node, Encord gates peer annotators from starting their subtask until the first annotator completes theirs.

<Note>This gating applies only to consensus annotation stages where **Show peer annotations** is enabled. Consensus stages without this setting are unaffected.</Note>

The gating works as follows:

* The **first annotator's** **Initiate** button is always available immediately.
* The **Initiate** button for all other peer annotators (every subtask after the first) is **disabled** until the first annotator completes their subtask.
* When a peer annotator hovers over their disabled **Initiate** button, a tooltip displays: *"The first annotation must be completed before peer annotations can be initiated."*
* Once the first annotator completes their subtask, the **Initiate** button becomes enabled for all remaining peer annotators.

This gating ensures that peer annotators can view the initial annotation before adding their own, which is the intended purpose of the **Show peer annotations** setting.

<Tip>For full details on configuring the **Show peer annotations** setting, see the [Consensus Annotation Workflows](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus) page.</Tip>

***

## Agent Configuration Protection

<Warning>When a Workflow stage contains queued tasks, agent configuration controls are disabled to prevent disruption of active processing.</Warning>

If you need to modify an agent configuration for a stage that has tasks:

1. Navigate to the Queue and select the stage containing the tasks
2. Move the tasks to another stage using the **⋯** row menu or the **Actions** menu
3. Return to the Workflow editor to modify the agent configuration
4. Move the tasks back to the stage if needed

This protection ensures that tasks are not left in an inconsistent state when agent configurations change.

***

## Starting Annotation or Review

To begin working on tasks directly from the Queue:

1. Navigate to the relevant Workflow stage using the stage list on the left.
2. Click **Start task** to pick up the next available task, or click **Initiate** next to a specific task to open it directly.
3. The task opens in the Label Editor.

<Tip>
  Use the **Start task** button for a faster, queue-driven workflow. Use **Initiate** when you need to open a specific task by name.
</Tip>

***

## Related Pages

<div lang="en">
  <head>
    <meta />

    <meta name="viewport" />

    <title>Clickable Div</title>
  </head>

  <div>
    <a href="/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates">
      Workflows and Templates
    </a>

    <a href="/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects">
      Manage Annotation Projects
    </a>

    <a href="/platform-documentation/Annotate/roles-and-permissions#projects">
      Project Roles and Permissions
    </a>

    <a href="/platform-documentation/Annotate/annotate-projects/annotate-project-analytics">
      Project Analytics
    </a>
  </div>
</div>


# Workflows and Templates
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates



Workflows are a powerful tool for designing and building Projects, allowing you to control how tasks move through different stages and how those stages interact.

## Creating Workflows

<Note>Workflows are created when [creating new annotation Projects](/platform-documentation/GettingStarted/gettingstarted-create-project), and when creating [Workflow templates](#templates).</Note>

<iframe title="YouTube video player" />

* **Manage Collaborators** allows you to seamlessly add users to your Workflow as collaborators, which can be added to different stages of the workflow.

* **Add stage** allows you to add more stages to your Workflow.

***

## Workflow Stages

This section contains details for all *Workflow library* components.

<Note>Only ANNOTATE, CONSENSUS, and AGENT nodes can be the first node after the START node in a workflow.</Note>

<Tip>To add library components to the canvas, click the **Add stage** button and then drag-and-drop the components onto the canvas.</Tip>

***

<AccordionGroup>
  <Accordion title="Start">
    #### Start

    <div>
      <img />
    </div>

    **Start** represents the beginning an annotation task through your Workflow, and can therefore only be used once in a Project. It must have a connector linking it to the next stage. It displays the [Datasets](/platform-documentation/Annotate/annotate-datasets/annotate-datasets) connected to the Project, and the selected [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies).
  </Accordion>

  <Accordion title="Annotate">
    #### Annotate

    <iframe title="YouTube video player" />

    **Annotate** represents an annotation stage, during which a group of annotators adds labels to tasks assigned to them.

    Click an **Annotate** card on the canvas to edit. Click **x** next to the name to exit edit mode.

    Click the *Edit* icon to edit the name of the annotation stage.

    <Tip>
      Annotation instructions can be added in the Project's *Settings* after the Project is created.
    </Tip>

    The stage contains all available annotators selected by default. Specific annotators can be selected in the **Selective** tab. Only collaborators that are [added to the Workflow](#managing-collaborators) are available for selection. Click **Add** to confirm the selection.

    <Note>Only collaborators with the *Annotator* or the *Annotator & Reviewer* roles are available for selection. All Admins and Team Managers are part of all annotation stages and therefore cannot be added, or removed.</Note>

    A Webhook can optionally be added to an annotation stage to send out notifications whenever a task is submitted. Click the **Edit** icon next to **Webhook** and add the URL of the server you want to receive notifications on. Once a valid URL is added and the Workflow saves, a **Signing Secret** becomes available that can be used to [verify that incoming notifications are genuinely from Encord](/platform-documentation/Annotate/annotate-webhooks-notifications#verifying-webhook-signatures).

    **Advanced Settings**

    **Allow task reassessment**: When enabled, annotators can see and review the same task again later in the workflow. Default: Disabled.

    **Require skip reason**

    Specify whether annotators must provide a reason before skipping a task.

    **Priority on re-entry**
    Specify when a task re-enters this stage, that task priority is automatically set to this value (0 = lowest, 100 = highest).

    **Task visibility**: Set **Unassigned tasks** to **Hidden** so users with the *Annotator*, *Reviewer*, or *Annotator & Reviewer* roles can only see tasks assigned to them. Admins and Team Managers can view all tasks, including unassigned ones. When **Unassigned tasks** is set to **Visible**, set **Tasks auto-served in the editor** to **Any available task** or **Assigned tasks only**. With **Assigned tasks only**, **Start task** and automatic task serving in the Label Editor offer only tasks assigned to the user. Users can still click **Initiate** to start a specific unassigned task.
  </Accordion>

  <Accordion title="Label Checkpoint">
    #### Label Checkpoint

    <div>
      <img />
    </div>

    The **Label Checkpoint** stage saves all tasks that pass through it to a specified branch. Fill in the following fields:

    * **Branch name**: Specify a name for the branch to store the labels.
    * **On re-entry**: Specify the behavior of tasks that re-enter the Label Checkpoint stage. Options are:
      * **Skip**: Skips the task.
      * **Overwrite**: Overwrites the existing labels in the branch with the new labels.

    <Note>
      Different label branches can then be seamlessly compared and viewed in the Label Editor using the [branch overlay button](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#branch-overlay-labels).
    </Note>

    <a href="https://www.loom.com/embed/795d49df662946d0b85bad2adc57ae2a" aria-label="Watch: Create & Display label branches" />
  </Accordion>

  <Accordion title="Routers">
    #### Routers

    A **Router** splits the path that *annotate* and *review* tasks take through the workflow. The following types of router are available:

    * [Percentage router](#percentage-router).
    * [Collaborator router](#collaborator-router).
    * [Metadata router](#metadata-router).

    <div>
      <iframe />
    </div>

    #### Percentage router

    <div>
      <img />
    </div>

    Pathways that data units take through the Workflow can be split according to a certain percentage of annotation tasks. For example, 50% of tasks get sent to *review stage A*, while the other 50% of tasks get sent to *review stage B*, splitting the workload between two different groups of reviewers.

    <div>
      <img />
    </div>

    Once the router selects a route for a given task, it is routed the same way until the routing percentages are updated. This means that if a task passes through a percentage router and is routed to *review stage A* on its first pass, it is routed to *review stage A* on each consecutive pass.

    <Note>Routing percentages can be changed after Project creation. Changing routing percentages resets the percentage router, and may alter the pathway taken by a given task. </Note>

    #### Collaborator router

    <div>
      <img />
    </div>

    Determine the paths that data units take through your workflow based on users. For example, if *user A* completes a task it gets sent to be reviewed by *review stage A*, while a task completed by *user B* gets reviewed in *review stage B*.

    <div>
      <img />
    </div>

    The *Or else* option accounts for all collaborators not explicitly added to the router. In this example they are directed to *review stage C*.

    1. Click **Add pathway** to choose a subset of collaborators that form the pathway. - only collaborators present in the previous stage can be selected. There is no limit on the amount of pathways you can create.

    2. Click **Add** to finish a pathway.

    <Note>Collaborators can only be added to the **Router** after an input is connected.</Note>

    #### Metadata router

    <Info>
      This feature is only available to Curation Package customers.
    </Info>

    <iframe title="YouTube video player" />

    Determine the paths that data units take through your Workflow based on the values of their [custom metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata). For example, tasks where `country` equals `UK` get sent to *review stage A*, tasks where `priority` is greater than `5` get sent to *review stage B*, and everything else follows the *Default* path.

    Each **route** is a condition made up of a metadata field and a value to match against it. The available match operators depend on the field's type in your organization's [metadata schema](/platform-documentation/Curate/custom-metadata/index-metadata-schema):

    | Field type      | Available operators                              |
    | --------------- | ------------------------------------------------ |
    | String / Enum   | equals                                           |
    | Boolean         | is `true` / is `false`                           |
    | Number          | equals, greater than, less than, between (range) |
    | Date / Datetime | after, before, between (range)                   |

    For **Enum** fields, you select the value to match from the values declared in the metadata schema.

    A task is sent down the **first route** whose condition it matches, evaluated top to bottom. Tasks that do not match any route follow the **Default** path (shown as a dashed connection), so every task always has a destination.

    1. Click **Add route** to create a route, then choose the metadata field, operator, and value that define its condition.

    2. Connect each route—and the **Default** path—to the next stage it should feed into.

    <Note>Routes can only be added to the **Router** after an input is connected. The metadata fields available to route on are read from your organization's client metadata schema.</Note>

    <Tip>The Metadata router appears as a stage in the **Queue** so you can monitor how many tasks are currently passing through it.</Tip>
  </Accordion>

  <Accordion title="Review">
    #### Review

    <iframe title="YouTube video player" />

    **Review** represents a review stage where tasks labeled in an annotation stage are reviewed.

    <Note>To attach the *Rejected* node of the review stage to another review stage, contact [support@encord.com](mailto:support@encord.com)</Note>

    Click a **Review** card that has been added to the canvas to edit. Click **x** next to the name to exit edit mode.

    Click the *Edit* icon to edit the name of the review stage. This is particularly useful when your Project has multiple review stages.

    <div>
      <img />
    </div>

    The stage contains all available reviewers selected by default. Specific reviewers can be selected by clicking the **Review** component, and choosing the **Selective** tab seen above. Only collaborators that have been added to the [Workflow](#managing-collaborators) or the [Project](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#manage-project-collaborators). Click **Add** to confirm the selection.

    <Note>Only collaborators with the *Reviewer* and *Annotator & Reviewer* roles are available for selection. All Admins and Team Managers are part of all review stages and cannot be removed.</Note>

    <div>
      <img />
    </div>

    **Advanced Settings**

    **Allow task reassessment**: When enabled, reviewers can review the same task multiple times as it moves through the Workflow. This also allows a user to review tasks they previously annotated. Default: Enabled.

    **Require comment on rejection**: When enabled, reviewers must enter a comment before rejecting labels or a task in the standard Label Editor. A task rejection comment is saved as a file issue that applies to the whole task. Issue tags alone do not satisfy the requirement. The Figure custom editor's rejection modal and rejections made through the SDK do not enforce this setting. Default: Disabled.

    #### Strict review

    <Note>Strict review is enabled by default, but can be disabled under *Advanced settings*.</Note>

    *Strict review* ensures that crucial details are not overlooked during a review stage. Strict review aids in assuring higher accuracy when reviewing annotations.

    *Strict review* stages do not auto-advance to the next review task after [bulk approving or rejecting](/platform-documentation/Annotate/annotate-label-editor#approve-and-reject-all-in-frame-buttons) labels. Reviewers can make adjustments to their review, and add comments when rejecting tasks with missing annotations.

    <AccordionGroup>
      <Accordion title=" Video Tutorial - Strict review & change review judgment ">
        <div>
          <iframe />
        </div>
      </Accordion>
    </AccordionGroup>

    <div>
      <img />
    </div>

    #### Whole task review

    Allows reviewers to approve or reject the entire task with a single decision instead of reviewing each label individually.

    #### User assignment restriction

    The *User assignment restriction* feature prevents team members working on tasks in the current stage that they have done in previous stages. This can prevent individuals with the *Annotator & Reviewer* role from being assigned their own annotations to review.

    This feature does not apply to users with the *Admin* or *Team Manager* roles, since they are added to each stage by default and cannot be removed.

    <div>
      <img />
    </div>

    Enable the toggle to implement *User assignment restriction*.

    #### Task visibility

    Set **Unassigned tasks** to **Visible** or **Hidden** in the Task queue for Reviewers. When unassigned tasks are visible, set **Tasks auto-served in the editor** to **Any available task** or **Assigned tasks only**. With **Assigned tasks only**, **Start task** and automatic task serving in the Label Editor offer only tasks assigned to the reviewer. Reviewers can still click **Initiate** to start a specific unassigned task.
  </Accordion>

  <Accordion title="Agent">
    #### Agent

    <iframe title="YouTube video player" />

    The **Agent** component represents an Agent. It triggers a custom operation each time a task passes through the Agent stage. The exact operation being triggered is configured using the Encord SDK.

    To fully connect an Agent to other Workflow components you must add pathways that allow you to create connections from the Agent stage to other components. To add a pathway, click **+** next to *Add pathway* and give the pathway a meaningful name. Repeat this step for each additional pathway you want to add.

    <Tip>Learn more about Agents in our  [Agent section](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview)</Tip>
  </Accordion>

  <Accordion title="Export">
    #### Export

    <div>
      <img />
    </div>

    **Export** represents a stage in a Project's Workflow that automatically syncs labels to your cloud storage as tasks pass through it.

    Every task that passes through the Export stage is synced to your chosen storage destination. Once the sync completes, tasks automatically continue to the next stage in your Workflow. This allows you to build a fully automated labeling pipeline, from task creation through to label delivery, without any manual exports. For more information, see [How to Export Labels](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels).

    <Note>
      When the same task passes through the export node more than once, its labels are overwritten each time.
    </Note>

    #### Export format

    When configuring a cloud Export node, you can choose the format in which labels are written to your storage destination. The **Format** dropdown offers two options:

    * **Encord JSON** (default) — exports labels in Encord's native JSON format.
    * **YOLO** — exports labels directly in YOLO format, suitable for use with YOLO-based object detection, segmentation, or OBB training pipelines.

    <Note>The YOLO export format option may not be visible to all users. Contact your Encord account team if you do not see this option.</Note>

    #### YOLO export settings

    When you select **YOLO** as the export format, a **Class mapping** selector appears. This selector lists the ontology external-ID namespaces configured on the Project's Ontology. Encord uses the selected namespace to resolve ontology features to YOLO class numbers at export time.

    <Note>Class numbers are resolved live from the Ontology's current external IDs each time a task is exported — they are not snapshotted when the node is saved. If you update your Ontology's external IDs after configuring this node, the exported class numbers will reflect the updated mapping.</Note>

    <Note>Namespace names are case-sensitive. Ensure the namespace name you select here matches the name configured in your Ontology's external IDs settings exactly.</Note>

    <Warning>Existing Export nodes already configured with YOLO format remain visible and editable even when the YOLO\_LABEL\_EXPORT feature flag is disabled, so that existing configurations are not hidden or lost.</Warning>

    **To configure YOLO export on a cloud Export node:**

    <Note>Before configuring YOLO export, ensure your Ontology has at least one external-ID namespace configured. The **Class mapping** selector is disabled if no namespaces exist on the Ontology.</Note>

    <Steps>
      <Step title="Select YOLO format">
        In the Export node settings panel, open the **Format** dropdown and select **YOLO**.
      </Step>

      <Step title="Select a class mapping namespace">
        Under **Class mapping**, select the ontology external-ID namespace that maps your ontology features to YOLO class numbers.

        A preview panel displays up to 5 feature-to-class-number mappings for the selected namespace, so you can confirm the correct namespace is chosen.
      </Step>

      <Step title="Configure ontology mappings (if needed)">
        If no namespaces are available, the **Class mapping** selector is disabled and a prompt appears. Click **Configure Ontology Mapping** to open the Ontology's external IDs settings page in a new tab and set up your YOLO class IDs before returning to save the node.
      </Step>

      <Step title="Save the Workflow">
        Click **Save** to save the Workflow. If YOLO format is selected but no class mapping namespace is chosen, the Workflow cannot be saved and displays the error: *YOLO export requires a class mapping to be selected.*
      </Step>
    </Steps>

    <Tip>The Workflow graph node card displays the selected format and, when YOLO is chosen, the name of the selected class mapping namespace — making it easy to review your export configuration at a glance.</Tip>
  </Accordion>

  <Accordion title="Complete">
    #### Complete

    **Complete** represents the stage of a Project at which a task is marked as complete, and can therefore only be used once per project.

    Having passed through your Workflow, it was deemed to be acceptable data for the training of machine learning algorithms. Complete tasks can still be accessed by admins.

    Optionally, add a [Webhook](/platform-documentation/Annotate/annotate-webhooks-notifications) to this stage to receive notifications whenever a task arrives at the **Complete** stage. Adding a valid Webhook URL and saving the Workflow generates a **Signing Secret** that can be used to [verify that incoming notifications are genuinely](/platform-documentation/Annotate/annotate-webhooks-notifications#verifying-webhook-signatures) from Encord.

    <FinalStageReopen />
  </Accordion>

  <Accordion title="Parallelization">
    #### Parallelization

    <iframe title="YouTube video player" />

    Parallelization splits a single annotation task into independent branches, each handling specific Ontology classes. Different annotators can work on different branches simultaneously, allowing specialized teams to annotate different parts of the same task in parallel.

    For example, assign one team to annotate vehicles, another to pedestrians, and a third to cyclists - all working on the same data concurrently instead of sequentially.

    <Note>
      **Parallelization vs Consensus**

      * Parallelization assigns different classes to different annotators in parallel.

      * Consensus assigns the same task to multiple annotators independently and compares their results. Use Parallelization to split work by class. Use Consensus to measure agreement.
    </Note>

    **Configure branches**

    Each branch represents one parallel stream of work. You can have up to 10 branches per Parallelization node.

    To add a branch:

    1. Click **Add branch** in the settings panel. A new branch appears with a default name.
    2. Click a branch to expand its settings.
    3. Specify a Branch name. Give the branch a descriptive name, such as the class group or team responsible for it (example: "Vehicles", "Pedestrians").
    4. Specify the *Classes*. Select the ontology classes that annotators in this branch will label. A class can only belong to one branch. If a class is already assigned to another branch, it is disabled in the selector and a conflict warning is shown.

    <Note>
      * Required classes are marked with a red indicator in the class selector.

      * You cannot modify branches while tasks are actively in progress on the node. Complete or reassign active tasks before making changes.
    </Note>

    5. Assign annotators to a branch. Each branch has an independent Annotate sub-node that controls who can work on it.

    6. Add a review stage to a branch. Each branch can optionally include its own review step. Branches can have review enabled or disabled independently.

    When a reviewer approves a task, it returns to the Parallelization node. When a reviewer rejects a task, it is sent back to the annotation step within the same branch.
    To remove a review stage from a branch, click the remove icon next to the review sub-node in the branch settings.

    **How tasks flow through a Parallelization node**

    1. A task enters the Parallelization node from the upstream node.
    2. The node creates one sub-task per branch.
    3. Each sub-task is assigned to the annotators configured for that branch.
    4. Annotators in each branch see only the classes assigned to their branch.
    5. If a branch has review enabled, the sub-task moves to the review step after annotation.

    <Note>
      Once all branches are `Complete`, the task exits the Parallelization node and continues through the Workflow.
    </Note>

    **Constraints and limits**

    * Maximum 10 branches per Parallelization node.
    * Each ontology class can be assigned to only one branch. Assigning the same class to multiple branches is not allowed.
    * Branch configuration cannot be changed while tasks are active in the node.
    * At least one branch is required. A Parallelization node with no branches is invalid.

    **Tips**

    * Organize branches around annotator specialisms. Teams with domain expertise in specific object types will label faster and more accurately when scoped to those classes.
    * Add review to high-priority or high-complexity branches only, rather than all branches, to keep overall cycle time down.
    * Use descriptive branch names. Branches appear in the task queue and admin views, making it easier to monitor progress per class group.
    * If all branches cover the same classes, consider using a Router node instead to distribute tasks by percentage or priority rather than by class.
  </Accordion>
</AccordionGroup>

***

### Managing collaborators

<div>
  <iframe />
</div>

***

#### User permissions

| Permission                     | Admin | Team Manager | Reviewer    | Annotator     | Annotator & Reviewer |
| ------------------------------ | ----- | ------------ | ----------- | ------------- | -------------------- |
| Attach / Detach datasets       | ✅     | ❌            | ❌           | ❌             | ❌                    |
| Attach / Switch ontology       | ✅     | ❌            | ❌           | ❌             | ❌                    |
| Delete                         | ✅     | ❌            | ❌           | ❌             | ❌                    |
| Invite team members            | ✅     | ✅            | ❌           | ❌             | ❌                    |
| Manage team permissions        | ✅     | ✅            | ❌           | ❌             | ❌                    |
| Manage admins                  | ✅     | ❌            | ❌           | ❌             | ❌                    |
| Annotate & review tasks        | ✅     | ✅            | Review only | Annotate only | ✅                    |
| Confirm annotations            | ✅     | ✅            | ❌           | ❌             | ❌                    |
| Control assignments and status | ✅     | ✅            | ❌           | ❌             | ❌                    |

#### Workflow stage level collaborators

Collaborators can be added to a workflow stage by clicking **+** on a card that has been added to the workflow canvas.

<div>
  <img />
</div>

Learn how to add collaborators to different stages of a Project by visiting the relevant sections in this document:

* [**Annotate**](#annotate) collaborators.
* [**Review**](#review) collaborators.
* Collaborator type [**Router**](#routers).

If no collaborators are specified at a given stage, all users with permissions are added by default.

For example, if no collaborators are specified at an **Annotate** stage then all collaborators with the following roles are added by default:

* Annotator
* Annotator & Reviewer
* Team Manager
* Admin

***

## Templates

Workflow templates allow you to save and reuse your most common workflows. You can then use these templates to create new annotation Projects, ensuring consistency and efficiency.

### Create Templates

New Workflow templates can be created each time a new Workflow is created.

1. Navigate to the **Projects** section of the Encord platform.
2. Navigate to the **Templates** tab.
3. Click **Create template**.

<div>
  <img />
</div>

4. Create your Workflow. Ensure your Workflow has a title.
5. Click the **Create workflow template** button.
   The template is saved in the custom templates section.

<div>
  <img />
</div>

### Edit Templates

You can edit Workflow templates after they have been created.

1. Navigate to the **Projects** section of the Encord platform.
2. Navigate to the **Templates** tab.
3. Select the template you want to Edit.
4. Click the **Edit** button in the top-right.
5. Edit the template.
6. Click **Save changes**.

<Note>You can not edit the start node.</Note>

### Template Collaborators

Template collaborators are annotators and reviewers that can be assigned to Workflow stages.

<AccordionGroup>
  <Accordion title="Invite Collaborators">
    1. Click the **Collaborators** button.

    <div>
      <img />
    </div>

    <AnnotatorLabelsTasksInTheProject />

    3. Type the email address of the user you want to add and select the user from the list.

    4. Click the **Add** button to add the user with the specified role.

    <div>
      <img />
    </div>
  </Accordion>

  <Accordion title="Manage Users">
    1. Click the **Collaborators** button.

    <div>
      <img />
    </div>

    2. Click the **Manage** tab.

    * **Change collaborator role**: Click the dropdown and select a new role.
    * **Remove collaborator**: Click the red *Remove* icon in the remove column.

    <div>
      <img />
    </div>
  </Accordion>
</AccordionGroup>

### Manage Template Access

Template Access determines which users can edit, share, and delete the template.

<AccordionGroup>
  <Accordion title="Invite Users">
    1. Click the **Manage template access** button.

    <div>
      <img />
    </div>

    2. Search for the collaborator or the [group](/platform-documentation/General/general-workspace-settings#user-groups) you want to add. Multiple collaborators and groups can be added at once.

    <Note>
      Only group members are added when a group is assigned to a Project. Group managers are not included.
    </Note>

    3. Select a role. You can assign the following roles to collaborators:
       * **User**: Can view the template.
       * **Admin**: Grants full administrative control over the template. This action is irreversible.

    4. Click **Add**.
  </Accordion>

  <Accordion title="Edit User Role">
    <Note>
      Only template admins can modify collaborator roles. Admin roles cannot be changed, not even by other admins.
    </Note>

    1. Click the **Manage template access** button.

    <div>
      <img />
    </div>

    2. Click the user role in the *Role* column
    3. Select a new role from the dropdown.

    <div>
      <img />
    </div>
  </Accordion>

  <Accordion title="Remove User">
    1. Click the **Manage template access** button.

    <div>
      <img />
    </div>

    2. Click the red *Remove* icon in the remove column.
  </Accordion>
</AccordionGroup>

### Delete Templates

To delete a template, click the red *Delete* icon next to the template.

<div>
  <img />
</div>

## Editing Workflows

<Note>Only ANNOTATE, CONSENSUS, and AGENT nodes can be the first node after the START node in a workflow.</Note>

<table>
  <thead>
    <tr>
      <th>Workflow Editing</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Add new stages</td>

      <td>
        * Annotate stages: Add manual annotation steps
        * Review stages: Insert quality control layers
        * Consensus stages: Add agreement-based validation
        * Agent stages: Integrate AI model predictions
        * Router stages: Add task routing/distribution logic
      </td>
    </tr>

    <tr>
      <td>Delete stages</td>

      <td>
        * Remove empty stages: Delete stages with zero tasks
        * System validation: Automatic checking prevents problematic deletions

        <Note>
          Any stage containing tasks cannot be deleted. Move tasks to a different stage before deleting a stage.
        </Note>
      </td>
    </tr>

    <tr>
      <td>Modify workflow connections</td>

      <td>
        * Change edge directions: Alter task flow paths
        * Expand router pathways: Add new routing options
        * Adjust percentage routing: Modify router distribution percentages
      </td>
    </tr>

    <tr>
      <td>Workflow management</td>

      <td>
        * Save changes: Persist workflow modifications
        * Re-name: Change the name of stages
        * Pause project: Stop task flow during Workflow modifications
        * Track last edited: See modification history and who made changes.

        <Note>
          - Encord tracks all edits so if we need to investigate / roll back we are capable of doing so. Not all logs are exposed to customers.
        </Note>
      </td>
    </tr>
  </tbody>
</table>

Edit Workflows from the **Annotate > Projects > \[select a Project] > Workflow** page.

<Warning>
  * You CANNOT delete stages that contain tasks. If you want to delete a stage that has tasks, first move the tasks to a different stage and then delete the stage.
  * You CANNOT delete COMPLETE stages.
</Warning>

**Edit standard Workflows**

<iframe title="Loom Video" />

**Edit Consensus Workflows**

<iframe title="Loom Video" />

### Limitations

Editing Workflows has the following limitations:

* Cannot change an Annotate stage to a Review stage. You must delete the stage and add a different stage.
* Cannot change fundamental stage configurations for Consensus stages.
* Cannot modify completed tasks. Historical task data remains unchanged
* Cannot delete labels/annotations. Existing annotation data is protected by blocking deleting stages that have tasks.


# Consensus Workflows
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus



Consensus, in Encord, provides the ability for one or more reviewers to directly compare the labels on a data unit, generated by 2 or more annotators. Annotators do not see what other annotators have labeled. Reviewers can, depending on the settings configured in a Consensus block, select the best individual labels/classifications on a data unit or for agreement/correctness on their labels across an entire data unit (bulk label selection). In both cases, many annotation branches come in and the reviewer decides on the best annotations (individually or in bulk) and one branch comes out.

So in short, multiple annotators label a data unit, and a reviewer can decide on the best labels individually (**Refine and Review**) or in bulk (**Determine consensus**).

<Note>Only ANNOTATE, CONSENSUS, and AGENT nodes can be the first node after the START node in a workflow.</Note>

<Info>Consensus supports Object labels and Classifications on images, image groups, image sequences, videos, audio files, text files, PDFs, Data Groups (Review and Refine only), and DICOM series.</Info>

<Note>
  **Parallelization vs Consensus**

  Parallelization assigns different classes to different annotators in parallel. Consensus assigns the same task to multiple annotators independently and compares their results. Use Parallelization to split work by class. Use Consensus to measure agreement.
</Note>

## Consensus Basics

<iframe title="YouTube video player" />

Workflows direct who and how annotations, and reviews of those annotations, are performed on data units. The addition of the *Consensus* and *Archive* blocks brings the ability to get consensus on your annotations.

*Consensus* blocks include an ANNOTATE and REVIEW stage in a single block.

*ANNOTATE* blocks require:

* **# of annotators required for task**: Specify the number of annotators required to label a task (data unit) for the task to move to the REVIEW stage in the Consensus block.

* **Advanced - Allow task reassignment**: Specifies whether, in subsequent blocks, an annotator can annotate a task they have already annotated.

* Add and designate annotators to label the data. This could be from a pool of all annotators (**All**) on a Project or by selectively choosing annotators (**Selective**).

*REVIEW* blocks require:

* Specify the type of review by selecting either **Review and Refine** or **Determine consensus**. *Review and refine* allows reviewers to individually select any of the best labels/classifications on a data unit from any annotator. Reviewers can also edit any **Approved labels** or create new labels on the data unit. *Determine consensus* allows reviewers to select the best labels/classifications on a data unit from 1 annotator (bulk selection) and to determine if there is agreement on the labels/classifications across annotators on the data unit.

* **# of annotators required to agree** (*Determine consensus*): Specify the number of annotators that a reviewer decides have labels that are correct and in agreement on a task.

* **Advanced - Allow task reassignment**: Specifies whether, in subsequent blocks, a reviewer can review a task they have already worked reviewed.

*Archive* blocks provide a location for any task that reviewers deem "not in consensus" or "rejected".

Tasks move through Consensus Projects in the following way:

1. When the number of annotators specified in **# of annotators required for task** label the task, the task moves to REVIEW.

2. Reviewers compare the labels on the task:

   * *Review and refine* : Reviewers select the best individual labels/classifications from any annotator across the data unit. Reviewers can edit any *Approved labels* and add new labels to the data unit.

   * *Determine consensus* : Reviewers decide on the correctness and annotator agreement specified in **# of annotators required to agree**. The task moves to the next stage based on label correctness and whether consensus is reached.

3. Adding multiple Consensus blocks in sequence, means all labels from all previous Consensus blocks display for the reviewers in each subsequent Consensus block.

Encord provides the following default Consensus Workflow, when creating a Project:

<div>
  <img />
</div>

The default Consensus Workflow **Consensus** uses 2 Consensus blocks. The first block uses *Determine consensus* with the second using *Review and Refine*.

<Note>When using any Consensus Workflow in a Project, do not forget to add your annotators and reviewers to the ANNOTATE and REVIEW sections. Also, if needed, edit the values for **# of annotators required for task** and **# of annotators required to agree**, for each Consensus block.</Note>

## Show Peer Annotations

The **Show peer annotations** setting is a per-node option on a Consensus annotation workflow node. When enabled, peer annotators can view the first annotator's completed labels before adding their own, helping to improve annotation consistency and providing a reference for subsequent annotators.

### Peer annotator initiation gating

When **Show peer annotations** is enabled on a Consensus annotation node, Encord gates peer annotators from starting their task until the first annotator completes theirs.

The following behavior applies:

* **First annotator**: The **Initiate** button is always available immediately. The first annotator is never gated.
* **Peer annotators** (all subtasks after the first): The **Initiate** button is disabled until the first annotator completes their subtask. Hovering over the disabled button displays the tooltip: *"The first annotation must be completed before peer annotations can be initiated."*
* **After the first annotator completes**: The **Initiate** button becomes enabled for all peer annotators (subject to any existing task assignment restrictions).

<Note>This gating behavior only applies when **Show peer annotations** is enabled on the Consensus annotation workflow node. Projects without this setting enabled are unaffected.</Note>

## Create a Consensus Project

1. Log in to Encord.
   The Encord homepage appears.

2. Go to **Annotate > Projects > Annotation projects**.
   The *Annotation projects* page appears.

3. Click the **New annotation project** button.
   The *Create new project* page appears.

4. Click the **Load workflow template** button.
   The *Load from workflow template* modal appears.

5. Select a Workflow template that uses Consensus blocks from the workflow template list.
   *Consensus*, the default Consensus Workflow, appears at the top of the template list.

6. Click **Load template**.
   The Workflow template appears in the Project workspace.

7. Specify which type of consensus you want to use from the REVIEW block:

   * **Review and refine** (default value)
   * **Determine consensus**

8. (Optional) Selectively add your annotators and reviewers to the ANNOTATE and REVIEW sections of the Consensus block.

9. Specify the required value for **# of annotators required for task**.

10. Specify the required value for **# of annotators required to agree** if you selected *Determine consensus*.

11. Specify the **Advanced - Allow task reassignment** for both the *Annotate* and *Review* blocks. The default settings are *Disabled* for *Annotate* blocks and *Enabled* for *Review* blocks.

12. Complete configuration of the Project.

13. Click **Create project**.
    The Project appears in the Annotation project list.

## Consensus Advanced

When the default Consensus Workflow template does not suit your requirements, build your own Consensus Workflow template. You can add multiple Consensus, Annotate, Review, and Router blocks to a Workflow.

Here are a couple of examples.

<AccordionGroup>
  <Accordion title="Consensus - Determine consensus - Workflow">
    In this Consensus Workflow:

    * Total # of annotators: 6
    * Total # of reviewers: 2
    * **# of annotators required for task**: 4
    * **# of annotators required to agree**: 3

    The following diagrams follows a task through the Consensus Workflow until the labels on the task are correct and in consensus or incorrect and not in consensus.

    <div>
      <img />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Consensus - Review and Refine - Workflow">
    In this Consensus Workflow:

    Consensus Block:

    * Total # of annotators: 6
    * Total # of reviewers: 2
    * **# of annotators required for task**: 4
    * Reviewers see labels from all 4 annotators.

    Consensus Block 2:

    * Total # of expert annotators: 2
    * Total # of expert reviewers: 2
    * **# of annotators required for task**: 1
    * Expert reviewers see labels from all 5 annotators (4 from Consensus Block 1 and 1 from Consensus Block 2).

    The following diagrams follow a task through the Consensus Workflow until the labels on the task are correct and in consensus or incorrect and not in consensus. If consensus happens in the first Consensus block, the task goes directly to Complete.

    <div>
      <img />
    </div>
  </Accordion>
</AccordionGroup>

## Create a Consensus Workflow Template

<div>
  <iframe />
</div>

To create a consensus Workflow template, your template must include one (or more) Consensus block and one Archive block. Consensus blocks can be used with [Annotate](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate) [Percentage Router](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#percentage-router) blocks and [Review](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#review) blocks to build out your Workflow template.

<Tip>For more information on creating Workflow templates see [our documentation here](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#creating-workflows).</Tip>

**To create a Consensus Workflow template:**

1. Log in to Encord.
   The Encord homepage appears.

2. Go to **Annotate > Workflow templates**.
   The Workflow templates page appears.

3. Click the **New workflow template** button.
   The *Create Workflow template* page appears.

4. Click the **Invite collaborators** icon.
   The *Workflow Collaborators* dialog appears.

5. Add the required collaborators for the template.

<Note>
  * Consensus requires at least 2 annotators for the first block, and at least 2 reviewers per block.

  * In Consensus video tasks, the **Requirements** panel tracks frames still needing annotation. A frame is complete with either an **object label** or **classification** (classification alone is sufficient). The panel updates in real time, and task submission is blocked until all required frames are annotated.
</Note>

6. Click the **Add stage** icon.
   The Add stage dialog appears.

7. Drag and drop at least 1 **Consensus** block and 1 **Archive** block into the template creation workspace.

8. Specify the REVIEW settings for the block (**Review and refine** or **Determine consensus**).

9. Connect the **No Consensus** output of the Consensus block (the final Consensus block if you have more than one Consensus block) to the input of the **Archive** block.

10. Add other blocks to the template as you require.

11. In each block, specify collaborators to perform tasks. You can add all annotators and reviewers as pools (**All**) or you can specify specific annotators and reviewers for each block (**Selective**).

12. Specify a value for **# of annotators required for task** for the *Annotate* portion of the *Consensus* blocks.

<Note>
  **# of annotators required for task** is the number of annotators required to annotate a task (data unit) before the task (data unit) moves to the *Review* stage in the *Consensus* block.
  If you use 2 or more Consensus blocks in your workflow, we recommend specifying only 1 annotator for your second and subsequent Consensus blocks. This is because all annotators, and their annotations, from previous blocks appear in the review of subsequent reviews.
</Note>

12. (**Determine consensus** only) Specify a value for **# of annotators required to agree** for the *Review* stage in the *Consensus* blocks.

<Note>
  **# of annotators required to agree** is the number of annotators required to agree on ALL labels on a data unit before consensus is reached. Reviewers decide if annotators have correctly labeled a data unit and if the annotators are in agreement.
</Note>

13. Complete configuration of the template.

14. Save the template.

## What do different user roles see?

Certain tabs can only be accessed by specific users roles.

<div>
  | **Tab**   | Annotator | Reviewer\* | Annotator + Reviewer\* | Team Manager | Admin |
  | --------- | --------- | ---------- | ---------------------- | ------------ | ----- |
  | Summary   | ❌         | ❌          | ❌                      | ✅            | ✅     |
  | Explore   | ❌         | ❌          | ❌                      | ✅            | ✅     |
  | Queue     | ✅         | ✅          | ✅                      | ✅            | ✅     |
  | Workflow  | ❌         | ❌          | ❌                      | ✅            | ✅     |
  | Analytics | ✅         | ✅          | ✅                      | ✅            | ✅     |
  | Settings  | ❌         | ❌          | ❌                      | ✅            | ✅     |
</div>

<Note>
  When **Show peer annotations** is enabled on a Consensus annotation nodes, peer annotators (all subtasks after the first) cannot initiate their task until the first annotator completes theirs. This restriction applies to all roles (annotators, collaborators, and admins) and is not role-based. The first annotator's **Initiate** button is never affected by this restriction. Once the first annotator completes their subtask, the **Initiate** button becomes available to all peer annotators. Hovering over a disabled peer **Initiate** button displays the tooltip: *"The first annotation must be completed before peer annotations can be initiated"*.
</Note>

### Annotators

When working on consensus Projects, annotators have no changes to their workflow or within the Encord platform. Annotators simply need to annotate the tasks (data units) in their queue.

Annotators do not see the work of other annotators as they annotate their tasks in Consensus Projects.

**Advanced - Allow task reassessment**: When this feature is disabled, annotators CANNOT see this task again as the moves through the workflow. This means they CANNOT annotate a task again, once they have annotated the task. **Disabled** is the default setting.

#### Peer annotator task initiation

When **Show peer annotations** is enabled on a Consensus annotation node, peer annotators (all annotators after the first) cannot initiate their task until the first annotator completes theirs. The **Initiate** button appears disabled in the annotation queue, with a tooltip explaining: *"The first annotation must be completed before peer annotations can be initiated."*

Once the first annotator completes their task, the **Initiate** button becomes available to all peer annotators (subject to any existing task assignment restrictions). The first annotator's **Initiate** button is never affected by this restriction.

### Reviewers

When reviewing labels from a REVIEW block on Consensus Projects, reviewers have a new UI when they initiate a task for review.

<Note>The only annotator's work/labels that display in audit Review blocks or the Complete block, is the annotator you specify as the "best annotator".</Note>

When reviewing and refining labels from a REVIEW and REFINE block, reviewers see all the labels from all annotators.

**Advanced - Allow task reassessment**: When this feature is enabled, reviewers CAN see this task again as the moves through the workflow. This means they CAN review a task multiple times as the task moves through the workflow. **Enabled** is the default setting.

### Annotator & Reviewer

Users with the *Annotator & Reviewer* role can see both the ANNOTATE and REVIEW blocks in a Consensus. As an annotator, the user cannot see the labels from other annotators. As a reviewer the user can view all labels from all annotators (including themselves) because the **Advanced - Allow task reassessment** feature is **Enabled** by default.

**Advanced - Allow task reassessment**: What a user with the *Annotator & Reviewer* role can see or do depends on the block they are in.

* ANNOTATE block: When this feature is enabled, annotators CAN see this task again as the task moves through the workflow. This means they CAN review a task multiple times as the task moves through the workflow. **Disabled** is the default setting.

* REVIEW block: When this feature is enabled, reviewers CAN see this task again as the task moves through the workflow. This means they CAN review a task multiple times as the task moves through the workflow. This also means if the user annotated the task, they can review their own task. **Enabled** is the default setting.

### Admins and Team Managers

Admins and Team Managers can do the following:

* Annotate tasks
* Act as a reviewer on Review tasks
* **View** tasks
* Monitor the entire queue (Annotate and Review tasks). This includes which tasks are in progress in terms of the number of annotators working on a task with the number of annotators required to finish a task.
* Reassign annotation tasks

## Export Labels from Consensus Projects

<Info>Consensus Projects export ONLY the labels that come from the annotator's that are marked as "Best" on each data unit by reviewers. This means that only the best labels are exported for your ML training.</Info>

**To export labels from Consensus Projects**:

<iframe title="YouTube video player" />

<Info>Only Project admins can export labels</Info>

<Tip>Descriptions of all information contained in the export file can be found [in the export file reference](/platform-documentation/Annotate/annotate-export/annotate-export-json).</Tip>

<iframe title="YouTube video player" />

<Tip>
  To export labels for specific tasks:

  1. Select the tasks
  2. Click **Bulk actions**
  3. Select **Export**
</Tip>

1. Click **Export** while in a Project.

   The *Export labels* dialog appears.

2. Specify the following:
   * **Format:** Specify the format to export the labels (JSON or COCO).
   * **Stage:** Specify the Workflow stage to export the labels from.
   * **Generate signed URLs:** Specify whether to generate signed URLs for the data units that have labels.
   <Note>
     Enabling this option can significantly increase export times.
   </Note>
   * **Save as new version:** Specify to version the labels.
     * Provide a meaningful name for the label version.
   * **Labels to include:** Specify the labels to include. You can export all labels or select specific object or classification labels to export.

3. Click **Export**.

   A *Labels export in progress* toast message appears.

## Reopen/Reassign Consensus Annotate tasks

As annotators work through their queue of annotation tasks, each task is "locked" to the annotator that first opened that specific task. The task is no longer visible to other annotators in the Project. In a Project that uses a Consensus Workflow, tasks get locked once multiple annotators (as specified by the number of annotators required to annotate a task in a Consensus block) open a specific task. All annotators must complete the annotation task before the task can move to the Review stage. Admins and Team Managers can reassign/reopen a task. Reopening the task makes the task visible to all annotators in the Project, and any annotator in the Project can then work on the task. Reassigning the task allows Admins or Team Managers to specify the annotator that works on the task.

**To reopen/reassign an Annotate task:**

1. Log in to Encord.
   The Encord homepage appears.

2. Go to **Annotate > Projects > Annotate projects**.
   The *Annotate projects* page appears.

3. Click a Consensus Project from the Project list.
   The *Summary* page for the Project appears.

4. Click the **Annotate** block with the task you want reassigned.

   ![Reopen/Reassign Task](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/consensus-reassign-task.png "Reassign/Reopen a Task")

5. Expand the task you want to reassign.
   The row expands to display the users currently assigned to the task.

6. To reopen the task to any annotator on the Project:

   a. Click the 3 dots icon next to the annotator you want the task reopened from.
   The *Reopen* button appears.

   b. Click **Reopen**.
   The task becomes visible to all annotators in the Annotate queue. Any annotator can then "lock" the task (including the annotator the task was reopened from).

7. To assign a specific annotator to the task:

   a. Click the down arrow next to the annotator you want the task reassigned from.
   A drop-down menu appears with all annotators available on the Project

   b. Click the down arrow next to the user you want changed.
   A drop-down menu appears with other annotators available to perform the task.

   c. Select the annotator you want the task assigned to.

## Reopen Complete or Archive Consensus Tasks

<Warning>In Consensus Projects, tasks in the COMPLETE and ARCHIVE blocks CANNOT be reopened.</Warning>


# Review Consensus Projects
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus-review-project

Learn how to review consensus Projects.

<div>
  <iframe />
</div>

<div>
  <iframe />
</div>

Consensus Projects have the following types of reviewers:

* **Determine consensus**: Reviewers in these blocks are responsible for ensuring that labels made by one or more annotators are correct across an entire data unit. This allows for bulk label selection across a data unit.

<div>
  <img />
</div>

* **Review and refine**: Reviewers can select and edit the best specific label on an object or frame, from one or more annotators.

<div>
  <img />
</div>

## Determine Consensus

Reviewers on Consensus Projects have a different goal from Reviewers on other types of Encord Projects. Reviewers on Consensus Projects review ALL the labels on a data unit, made by a specified number of annotators. The reviewers then make a decision on whether there is agreement/consensus on ALL the labels on a task (data unit).

If the reviewer decides that ALL the labels on a data unit are correct/in agreement, the reviewer selects the annotators that are in agreement and clicks **Consensus reached**. If the reviewer decides that there is no agreement on the labels or that the labels are incorrect, the reviewer clicks **No Consensus**.

Currently, Object labels and Classifications are supported for consensus review on all data unit types. Data units are images, image groups, image sequences, videos, and DICOM series.

**To review labels on a Consensus Project:**

1. Log in to Encord.
   Your review task queue appears for the latest Project you are assigned for review.

2. Go to **Annotate > Projects > Annotate projects**.
   The *Annotate projects* page appears displaying a list of Projects you are assigned to review.

3. Click a Consensus Project.
   The Project opens with the *Review* populated with review tasks.

4. Click **Initiate** on a task.
   The *Reviewing* page appears.

5. Review the labels from each annotator.

<Info>**Determine Consensus** in Encord is based on Consensus for ALL labels on a data unit. A data unit being an image, an image group, an image sequence, a video, or a DICOM series. Encord Consensus is not granular to the label itself (yet). This means reviewers must ensure ALL labels on a data unit are in consensus before deciding consensus is reached.</Info>

The Reviewing page is different for single images and all other data units. When reviewing single images, expand each user to display their labels and decide on consensus. When reviewing videos, image groups, image sequences, and DICOM series a timeline appears under the data unit. Use the timeline to speed up reviewing all the labels on the data unit.

<Tip>Use the show-hide labels buttons, workspace settings, and the drag and select in the workspace to speed up your approved label selection and review process.</Tip>

**Single Image, Image Group**

<div>
  <img />
</div>

**Video, Image Sequence, DICOM Series**

<div>
  <img />
</div>

6. If the labels are correct:

a. Select the annotators that have done the best job of labeling the data unit.
The *Consensus reached* button becomes clickable once the required number of annotators required are selected.

b. Click the **Consensus reached** button.

c. Select the annotator that did the best job. That annotator's work on the data unit is used if an Admin or Team Manager export the labels for the data unit.

d. Click **Submit**.

**Single Image, Image Group**

<div>
  <img />
</div>

**Video, Image Sequence, DICOM Series**

<div>
  <img />
</div>

7. Click **No consensus** if the labels are not correct OR if not enough of the annotators have labeled the data unit correctly.

## Review and Refine Consensus Labels

Reviewers working in the Review and Refine block can see all labels from all annotators from a Consensus block. The reviewer is able to select the best labels from each object on a data unit and edit those labels or they can create new labels for the data unit.

The Review and Refine page is different for single images and all other data units. When reviewing and refining single images, expand each user to display their labels and decide on the best labels. When reviewing and refining videos, image groups, image sequences, and DICOM series, a timeline appears under the data unit. Use the timeline to speed up reviewing and refining all the labels on the data unit.

In the **Annotator labels** section, click **Approve classifications with total agreement** to approve classifications on which all annotators agree. Classifications with only partial agreement are not approved.

### Enhanced By-Label View

When using the **By label** view in Review and Refine mode, you'll notice several improvements designed to streamline your workflow:

* **Organized display**: Classifications appear before objects in the label list, making it easier to review different types of annotations in a logical order.
* **Hover-based visibility controls**: Eye icons for showing and hiding labels appear only when you hover over label rows, reducing visual clutter while keeping controls accessible.
* **Group-level visibility**: Toggle visibility for entire groups of related labels at once, or control individual annotations within each group.

<Tip>
  Use the show-hide labels buttons, workspace settings, and the drag and select in the workspace to speed up your approved label selection and review process.

  ![Optimize Review](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/projects-consensus-review-approve-labels.gif)
</Tip>

**To review and refine labels from a Consensus Project:**

Only data units for which consensus is not reached can be reviewed and refined.

1. Log in to Encord.
   Your review and refine task queue appears for the latest Project you are assigned for review and refinement.

2. Go to **Annotate > Projects > Annotate projects**.
   The *Annotate projects* page appears displaying a list of Projects you are assigned to review and refine.

3. Click a Consensus Project.
   The Project opens with *Review and Refine* populated with tasks.

4. Click **Initiate** on a task.
   The *Review and refine* page appears.

5. Review and refine the labels on each data unit.

**Single Image, Image Group**

<div>
  <img />
</div>

**Video, Image Sequence, DICOM Series**

<div>
  <img />
</div>

6. Click **Edit approved labels** to add new labels to the data unit or modify existing approved labels.

<Note>When editing approved labels, any changes you make are preserved even if you later revert the approval of those labels. This allows you to refine labels and maintain your edits throughout the review process.</Note>

7. Select the best labels for each object on the data unit.

8. Click **Approve labels**.
   The labels appear in the *Approved labels* list.

9. Select a label from the Approved labels list.

10. Click **Edit approved labels** if the labels need to be adjusted.

11. Click **Approve task** after selecting, refining, and creating the labels needed for the data unit.

12. Click **Reject task** if the labels on the data unit cannot be added or corrected so the labels on the data unit meet your needs.

## Frame and Tile Navigation

When reviewing consensus Projects with videos, image sequences, or Data Groups containing multiple tiles, the left sidebar displays frame numbers and tile names for each annotation. This helps you quickly identify where annotations are located and navigate to specific frames or tiles.

<Note>Frame numbers and tile names are displayed for annotations on videos, image sequences, DICOM series, and Data Groups with multiple tiles. Single images and image groups show only the annotation details.</Note>

**Frame Navigation**

* Click on any frame number to jump directly to that frame in the corresponding tile
* Frame ranges are displayed as individual numbers (for single frames) or ranges (for multi-frame annotations)
* Time stamps are shown instead of frame numbers when enabled in Project settings

**Tile Navigation**

* Tile names appear as badges next to frame information
* Clicking a frame number automatically switches to the correct tile if needed
* Each annotation shows which tile it belongs to, making it easier to review multi-tile data units

<Tip>Use frame and tile navigation to quickly jump between different parts of your data unit during review. This is especially helpful when comparing annotations from different annotators across multiple frames or tiles.</Tip>

## Group-Level Classifications

When reviewing tasks that contain Data Groups and certain types of data units (image groups, image sequences, videos, or DICOM series), you may encounter group-level classifications. Group-level classifications are classifications that apply to the entire Data Group instead of specific frames or tiles.

Group-level classifications are displayed with a **Global** icon to distinguish them from frame-specific or tile-specific classifications.

<Note>Group-level classifications are handled differently during consensus review. When approving a group-level classification from one annotator, any conflicting group-level classifications from other annotators for the same feature are automatically disabled to prevent conflicts.</Note>

## Advanced - Allow task reassessment

This feature is available in both the ANNOTATE and REVIEW blocks. It determines whether users can act on tasks they have already annotated or reviewed as those tasks progress through the workflow.

Users with the *Annotator & Reviewer* role can access both blocks in a Consensus.

* In the ANNOTATE block, they cannot see other annotators' labels.

* In the REVIEW block, they can view all labels (including their own) because this feature is enabled by default.

**Behavior by block**:

ANNOTATE block:
When enabled, annotators can see and review the same task again later in the workflow.
Default: Disabled.

REVIEW block:
When enabled, reviewers can review the same task multiple times as it moves through the workflow.
This also allows a user to review tasks they previously annotated.
Default: Enabled.

## Advanced - Task visibility

When **Unassigned tasks** is set to **Hidden**, users with the *Annotator*, *Reviewer*, or *Annotator & Reviewer* roles can only see tasks assigned to them. Admins and Team Managers can view all tasks, including unassigned ones.

When **Unassigned tasks** is set to **Visible**, set **Tasks auto-served in the editor** to **Any available task** or **Assigned tasks only**. With **Assigned tasks only**, **Start task** and automatic task serving in the Label Editor offer only tasks assigned to the user. Users can still click **Initiate** to start a specific unassigned task.


# Form Layouts
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/custom-layouts



An editor layout defines how the annotation interface is presented to labelers inside a Project. It controls what panels appear, where media is displayed, which classification fields and object panels are visible, and how those elements are arranged on screen.

Every Project created from a template comes with a pre-configured layout. You can use it as-is or customize it to match your workflow.

***

## Creating Form Layouts

<iframe title="YouTube video player" />

The **Task layout** card on the Project Overview page shows the current layout status:

* **Standard layout** — Your Project uses the default layout. No custom layout has been configured.
* **Form layout** — Your Project uses a custom layout you have configured.

<Tip>When your Project uses a form layout, hover over the **Task layout** card to reveal the **Edit** button.</Tip>

1. Open your Project and go to **Overview**.
2. Click **Switch to form** (or hover over the **Task layout** card and click **Edit** if a custom layout already exists).
   The layout builder opens, showing the current layout and a palette of components on the left.

## Previewing a Task Layout

You can preview the label editor experience directly from the Project Overview page without navigating away from it.

The **Task layout** card includes a **Preview** button alongside the **Edit**/**Set up** button. Clicking **Preview** replaces the right-panel analytics content with an embedded label editor preview so you can see exactly how your task layout appears to annotators.

<Note>The **Preview** button is disabled when the Project has no demo data and no linked datasets. Hover over the disabled button to see the tooltip: *"Link data to this project to see a preview."* Link at least one dataset to the Project to enable the preview.</Note>

**To preview a task layout:**

<Steps>
  <Step title="Open your Project Overview">
    Navigate to your Project and click **Overview**.
  </Step>

  <Step title="Click Preview on the Task layout card">
    Locate the **Task layout** card in the left panel. Hover over it and click the **Preview** button next to the **Edit**/**Switch to form** button.
  </Step>

  <Step title="Toggle between demo data and real project data">
    If your Project has demo data configured, you can toggle between demo data and your real project data within the preview panel.
  </Step>

  <Step title="Close the preview">
    Click **Hide preview** in the preview panel header to return to the standard analytics view.
  </Step>
</Steps>

<Tip>The preview state is reflected in the page URL as `?view=preview`. You can share or bookmark this URL to open the preview directly.</Tip>

<Info>Opening the preview is mutually exclusive with other Project Overview panels (Data, Ontology, and Layout modals). Only one panel can be active at a time.</Info>

<div>
  <img />
</div>

## Edit Layout

* **Add a component**: Drag a component from the palette and drop it onto the canvas. Drop zones appear as you drag to indicate where the component can be placed. You can also click the **Add item** button inside any container to open a popover and select a component to add.

* **Move a component**: Drag an existing component to a new position within the canvas.

* **Configure a component**: Click a component to select it. Its configuration options appear in the panel on the right. Changes take effect immediately in the preview.

* **Remove a component**: Select the component and click the delete icon in the configuration panel, or use the context menu on the canvas.

* **Revert to standard layout**: Click **Switch to standard layout** in the layout builder header to remove your form layout and return to the default layout. Encord displays a confirmation dialog before proceeding. After you confirm, the task layout preview on the Project Overview page refreshes immediately to reflect the standard layout.

* **Edit as JSON**: Toggle **JSON editor** to view and edit the layout as raw JSON. This is useful for copying layouts between Projects or making bulk changes. The editor validates the JSON structure on save.

## Layout Structure & Components

A layout is a tree of **containers** and **items**.

* **Containers** hold other containers or items. They arrange their children either horizontally (side by side) or vertically (stacked).
* **Items** are the leaf nodes. Items render a specific piece of the UI, such as a media player, a classification field, or an object panel.

You build layouts by dragging components from the palette into the canvas and nesting them inside containers.

* **Stack**: A vertical container. Children are arranged top to bottom. Use a Stack as the top-level wrapper for most layouts, or to group related fields below the media player. Stack containers are transparent wrappers — they do not render a card background.

* **Columns**: A horizontal container. Children are arranged left to right. Use Columns to place the media player and classification fields side by side. Columns containers are transparent wrappers — they do not render a card background.

* **Media**: Renders the media player for the current task — image, video, audio, or document. Every layout should include exactly one Media component. You can configure:

  * **Controls** — `full` shows all playback controls; `minimal` shows only essential controls.
  * **Autoloop** — automatically loops video or audio when playback reaches the end.

* **Field**: Renders a single classification field from the Project's Ontology. Form layouts only support **global classifications**. Global classifications apply to the entire data unit. Frame-level classifications apply to individual frames and are not supported in form layouts. When you add a Field component, you select which Ontology classification it maps to. Each Field component renders inside its own card. The display style depends on the field type:

  | Field type             | Display options         |
  | ---------------------- | ----------------------- |
  | Select (single choice) | Radio buttons, Dropdown |
  | Multiselect            | Checklist, Dropdown     |
  | Number                 | Number input, Slider    |
  | Text                   | Text area               |

  You can also mark a field as **read-only**, which displays its value but prevents labelers from editing it.

* **Object**: Renders an annotation panel for a single ontology object. The **Objects** section of the palette lists all objects defined in the Project's Ontology that have not yet been placed in the layout. You can search objects by name. When you add an Object component, it maps to the corresponding ontology object and displays a shapes icon in the layout preview and configuration panel.

  * **Read only** — check this option in the configuration panel to display the object panel without allowing annotators to make edits.

  <Note>Each object can appear in the layout only once. Objects already placed in the layout are automatically removed from the palette to prevent duplicates. Archived objects never appear in the palette.</Note>

* **Multi-step**: Renders a sequential step-by-step wizard. Each step contains its own set of fields. Use Multi-step for workflows where data must be captured in a specific order — for example, first annotating the front of a document, then the back. The Multi-step shell uses the standard page background, and fields inside each step render as individual cards.

## Palette Sections

The palette organizes available components into clearly labeled sections. A search bar at the top filters results across all sections simultaneously.

<AccordionGroup>
  <Accordion title="Global Classifications">
    ### Global Classifications

    The **Global Classifications** section lists all global classifications from the Project's Ontology that have not yet been placed in the layout. Hover over the info icon next to the section heading to see a popover explaining that only global classifications are supported in Custom Layouts.

    Global classifications apply to the entire data unit. Global classifications that you have already added to the layout are removed from this section automatically. Archived classifications are hidden from the palette entirely.
  </Accordion>

  <Accordion title="Unsupported">
    ### Unsupported

    The **Unsupported** section lists any frame-level classifications defined in the Project's Ontology. Frame-level classifications apply to individual frames rather than the entire data unit, and Form Layouts do not support them. These entries appear grayed out and cannot be dragged into the layout. Each entry shows a **Frame-level** label. Hovering over an entry displays the tooltip: *"Frame-level classifications are not supported in Form Layouts."*

    <Note>Unsupported classifications appear in palette search results under the **Unsupported** section when their name matches the search query. Archived classifications remain hidden from both the Global Classifications and Unsupported sections.</Note>

    The **Unsupported** section only appears when the Project's Ontology contains at least one frame-level classification. If all classifications are global, the section is not shown.
  </Accordion>

  <Accordion title="Edit Ontology">
    ### Edit Ontology

    An **Edit ontology** button is pinned to the bottom of the palette. Click it to open the Ontology editor without leaving the layout builder.

    <Note>The **Edit ontology** button is only visible to users with an Admin or Team Manager role on the Project.</Note>
  </Accordion>
</AccordionGroup>

## Object Table

The object table displays all instances of an object class in a compact, spreadsheet-like view alongside the media. Each row represents one instance; each column represents an attribute defined on that object in the Ontology.

<AccordionGroup>
  <Accordion title="Appearance">
    ### Appearance

    The object table uses a borderless, spreadsheet-like design. All field types — text, number, single-select, and multi-select — blend seamlessly into their cells without visible input borders or chrome.

    Column widths are fixed per field type:

    * **Select and multi-select columns** — 224 px wide.
    * **Text and number columns** — 176 px wide.
    * **Instance column** — labeled **Instance**; sizes to its content and displays a chip containing the object's shape icon and a numeric index (for example, `1`, `2`, `3`).

    Multi-select chips wrap within the column rather than expanding it. Text cells grow up to four lines before scrolling vertically. Single-select and multi-select fields open on click only; multi-select fields show a chevron indicator.

    A **footer summary bar** at the bottom of the table shows the total number of instances and columns (for example, `3 instances / 4 columns`).
  </Accordion>

  <Accordion title="Responsive width">
    ### Responsive width

    When the object table is placed next to media in a horizontal (Columns) layout, side panels maintain a stable width to prevent the object table from crushing the adjacent media pane:

    * Panels containing an object table use a fixed width of 40 rem.
    * All other side panels use a fixed width of 28 rem.
    * Both are capped at 50% of the row width.

    In vertical (Stack) layouts, the table uses a fixed flex basis to prevent it from collapsing.
  </Accordion>

  <Accordion title="Empty state">
    ### Empty state

    When no instances exist yet, the object table displays an empty state with a descriptive message and an **Add instance** button that includes its keyboard shortcut. The empty state always remains visible — it renders outside the scrollable table area so it is never clipped off-screen.

    The empty state message is context-aware:

    * When the draw tool is active, the message reads: *"Draw on the canvas to create the first \[object name]."*
    * Otherwise, the message reads: *"Create the first instance of the \[object name] object."*
  </Accordion>

  <Accordion title="Object table in the Layout Builder preview">
    ### Object table in the Layout Builder preview

    The Layout Builder preview shows a live representation of the object table with sample rows. The preview accurately mirrors the runtime editor, including:

    * An **Instance** column header with instance chips showing the object's shape icon and a numeric index.
    * Attribute column headers showing the attribute name, an attribute type icon, and a required marker (`*`) for any required attributes.
    * A labeled **+ Add** button in the trailing column header for adding new columns (when the ontology is editable).

    When an object has no columns yet, the preview shows one of the following in the trailing header cell:

    * A labeled **+ Add** button with dashed ghost cells below it — when the ontology is editable and you have permission to add columns.
    * A muted **No columns** label — when the ontology is not editable.

    In addition to the standard table appearance, the preview provides the following interactions for layout builders:

    * **Select a column**: Click a column header to highlight the entire column. The selected column is also highlighted in the configuration panel on the right, where you can edit its settings.
    * **Rename a column inline**: Click a column header to select it, then edit the column name directly in the header cell. Press `Enter` or click away to confirm the new name.
    * **Add a column**: Click the **+ Add** button in the header row. Select the column type from the dropdown — **Text**, **Number**, **Single select**, or **Multi select**. The new column is added immediately and selected in the configuration panel.

    <Tip>You can also add and configure columns from the configuration panel on the right side of the Layout Builder.</Tip>
  </Accordion>
</AccordionGroup>

## Add Items

Every container in the layout includes an **Add item** button. Clicking it opens a popover with the following sections:

* **Containers** — add a Stack or Columns container.
* **Media** — add the Media player (available only if no Media component is already present in the layout).
* **Classifications** — lists available global classifications from the Project's Ontology.
* **Objects** — lists available ontology objects that have not yet been placed in the layout, searchable by name.

Select any item from the popover to add it directly to the container.

## Global and Frame-Level Classifications

Form layouts only support global classifications. Global classifications apply to the entire data unit, while frame-level classifications apply to individual frames.

Frame-level classifications are visible in the palette under the **Unsupported** section so you can see which ontology fields exist but cannot be used in a form layout. You cannot drag them into the canvas.

<Warning>
  If your existing layout contains a frame-based classification and you attempt to remove the component that holds it, Encord displays a confirmation dialog before proceeding. Once removed, you cannot add the frame-based classification back to the layout — it will not appear in the palette.
</Warning>

## Conditional Display

Conditional display lets you control when a field is shown to annotators. Instead of always rendering every field, you can configure rules so that a field only appears when other fields' answers meet specific conditions. This keeps the annotation interface focused and reduces cognitive load for annotators.

<Info>
  Conditional display is available for both classification fields and object items in the layout builder.
</Info>

**To enable conditional display for a field:**

<Steps>
  <Step title="Select a field in the layout builder">
    Click a field or object item on the canvas. Its configuration panel opens on the right.
  </Step>

  <Step title="Locate the Conditional display section">
    Scroll to the **Conditional display** section at the bottom of the configuration panel.
  </Step>

  <Step title="Enable the toggle">
    Turn on the **Conditional display** toggle switch. The **Display rule** editor appears.

    <Note>The toggle is disabled if no other referenceable fields exist in the layout, or if the field is currently marked as **Required**. Add at least one other field to the layout, or turn off **Required**, before enabling conditional display.</Note>
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Build a display rule">
    ### Build a display rule

    When conditional display is enabled, the **Display rule** editor appears. A display rule consists of one or more conditions. Each condition specifies a source field, an operator, and a value. The field only renders when the conditions are met.

    **Match mode**

    At the top of the rule editor, select how multiple conditions are evaluated:

    * **Match all** — the field appears only when every condition is satisfied (AND logic).
    * **Match any** — the field appears when at least one condition is satisfied (OR logic).

    **Add a condition**:

    Click **Add condition** in the rule editor header to add a new condition row. Each condition row contains:

    1. A **field selector** — choose which other field's answer to evaluate.
    2. An **operator selector** — choose the comparison to apply (options vary by field type).
    3. A **value input** — enter or select the value to compare against.

    **Remove a condition**:

    Hover over a condition row to reveal the trash icon on the right, then click it to remove that condition. If you remove all conditions, conditional display turns off automatically.

    **Summary line**:

    At the bottom of the rule editor, a **Hidden until …** summary line describes the active rule in plain language, so you can confirm the logic at a glance.
  </Accordion>

  <Accordion title="Resolve labels that do not match display conditions">
    ### Resolve labels that do not match display conditions

    If a field already contains a label when its display conditions stop being met, the label remains stored. The field is hidden unless it is required. Required fields remain visible. The Label Editor displays a warning above the form. Click **Review** to open **Condition mismatches** in the Rules pane, where you can review the affected labels and their conditions.

    Click **Clear** beside a label to remove it, or click **Clear all** to remove all clearable mismatched labels. You can undo either action. You cannot clear a mismatch for a required field: its **Clear** control is disabled, and you must fix the conflict between the layout condition and the ontology requirement in the Project setup. In view-only and review modes, you can review mismatches but cannot clear them.

    Mismatched labels do not prevent submission. If any remain when you submit the task, click **View issues** to return to the Rules pane or **Submit anyway** to continue.
  </Accordion>

  <Accordion title="Advanced conditions (JSON-authored)">
    ### Advanced conditions (JSON-authored)

    <Warning>
      If a field's display condition was set by editing the layout JSON directly and uses logic that the visual editor cannot represent, the rule editor is replaced by a read-only notice: *"This field uses an advanced condition that can only be edited in the JSON view."* To switch back to the visual editor, click **Clear condition** to remove the advanced condition, then rebuild the rule using the visual editor.
    </Warning>
  </Accordion>

  <Accordion title="Conditional display and the Required setting">
    ### Conditional display and the Required setting

    <Warning>
      Conditional display and **Required** are mutually exclusive. A field cannot be both conditionally shown and required at the same time.

      * If a field already has display conditions configured, the **Required** toggle is disabled and a warning banner reads: *"A field with display conditions can't be required."*
      * If a field is already marked as **Required**, the **Conditional display** toggle is disabled. Turn off **Required** first to enable conditional display.
    </Warning>
  </Accordion>
</AccordionGroup>

## Canvas Badges

Field cards on the builder canvas automatically display inline badges that summarize each field's visibility relationships. These badges give you an at-a-glance view of dependencies without opening each field's configuration panel.

* **Hidden until …** — appears on a field card when that field has an active display condition. The badge shows the same plain-language summary as the rule editor's summary line. This badge is suppressed for required fields, since required fields always render regardless of conditions.

* **N field(s) depend on this answer** — appears on a field card when one or more other fields reference it in their display conditions. For example, if two fields are set to appear only when this field has a specific answer, the badge reads *"2 fields depend on this answer"*.

## Object Table

The configurable editor includes an object table that lists every instance of an object type in the current task. The table provides controls for managing instances directly, without switching to the sidebar.

### Per-instance row actions

Hovering over an instance row reveals a **…** (kebab) button on the right side of the row. Click it to open the action menu for that instance.

The menu contains the following actions, depending on the media type and instance state:

* **Track forwards** — Runs SAM-based tracking forward from the current frame. Only available for SAM-trackable shapes on frame-based media (video and multi-frame assets).
* **Track backwards** — Runs SAM-based tracking backward from the current frame. Subject to the same conditions as **Track forwards**.
* **Instantiate in frame** — Adds the instance to the current frame. Only shown when the instance is not already present on the current frame.
* **Delete** — Removes the instance. Encord displays a confirmation dialog before deleting.

<Note>Row actions are hidden when the editor is in view-only mode or when the table is in a disabled state.</Note>

### Frame range pills

For video and multi-frame assets, each instance row displays its frame ranges as pills beneath the instance name. These pills are for reference only — clicking a pill does not navigate to that frame.

<Note>Frame range pills display zero-based frame indices, which may differ from the frame numbers shown in the scrubber.</Note>

### Select tiles (Data Groups)

For Data Group assets, a tile picker dropdown appears in the object table header row. Use it to filter the instance list to a specific tile or view all tiles at once.

* Selecting a tile filters the table to show only instances belonging to that tile, and sets it as the active tile in the editor.
* Selecting **All tiles** shows instances across all tiles and clears the active tile filter.

## Layout Validation

Before you can save a custom layout, Encord validates the configuration and surfaces any errors that would result in an incomplete or broken annotation experience.

Encord checks for the following issues:

* **Empty containers** — A Stack or Columns container that contains no children. Add at least one component to the container, or remove it from the layout.
* **Empty Multi-step steps** — A step inside a Multi-step component that contains no fields. Add at least one field to the step, or remove the step.
* **Incomplete Slider configuration** — A Slider field with no minimum or maximum value set. Both values are required before saving.
* **Missing required classifications** — A classification marked as required in the Project ontology that has not been added to the layout. Every required classification must appear somewhere in the layout — either directly or inside a Multi-step step — before you can save.
* **Missing required objects** — An object with one or more required (non-archived) attributes that has not been added to the layout. Every such object must appear somewhere in the layout before you can save. This check mirrors the existing behavior for required classifications.

<Note>Validation errors appear in the header of the layout builder. Click an error message to highlight the affected component in the canvas. Errors related to missing required classifications or missing required objects do not highlight a specific component, since the field or object has not yet been placed in the layout.</Note>

Encord blocks saving until all validation errors are resolved. Review each error message, make the necessary changes, and then save the layout.

<Note>
  * To update your Project's Ontology without leaving the layout builder, click the **Edit ontology** button at the bottom of the palette.
  * The **Edit ontology** button is only visible to users with an Admin or Team Manager role on the Project.
</Note>


# Tabular Data Projects
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-projects/project-tabular-data



<Tip>
  We recommend reviewing our [end-to-end example](/end-to-end/Modalities/tabular/e2e-tabular-data) to get a practical grasp of using Tabular Data Projects.
</Tip>

<Note>
  Tabular Data currently supports [**CONSENSUS** Projects](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus) only.
</Note>

Tabular data Projects work a little differently than typical Projects in Encord. Annotators and Reviewers select from options columns for each row. You can use multiple columns for selection.

## Create Ontology for Tabular Data

Modify the following script example to create your Ontology.

<table>
  <thead>
    <tr>
      <th>**Items of Interest**</th>
      <th>**Notes**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`READ_ONLY_COLUMNS`</td>

      <td>
        * Specifies the columns you want your Annotators and Reviewers to see in the Label Editor.
        * Column count starts at 0.
        * Omit the columns in your CSV you do not want your Annotators and Reviewers to see.
      </td>
    </tr>

    <tr>
      <td>ANNOTATION\_COLUMNS</td>

      <td>
        * Specifies the columns your Annotators and Reviewers use to label data from. Your Annotators and Reviewers select answers from a drop down in these columns.
        * Specify the options available to Annotators and Reviewers using the files in `MAPPING_FIELD_OPTION_PATHS`. These files are single column files with one option available on each row.
      </td>
    </tr>

    <tr>
      <td>ONTOLOGY\_NAME</td>
      <td>Specifies the name for your Ontology.</td>
    </tr>

    <tr>
      <td>OBJECT\_NAME</td>
      <td>Specifies the name of the text region for each row in your CSV file. The script applies a label to each row in your CSV file using this text region.</td>
    </tr>
  </tbody>
</table>

```python tabular_create_ontology script theme={"dark"}

import pandas as pd
from encord.objects import OntologyStructure, Shape, TextAttribute
from encord.objects.attributes import RadioAttribute
from encord.user_client import EncordUserClient

# --- Configuration ---
ENCORD_SSH_KEY = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SHH private key
TASK_CSV_PATH = "/file/path/to/video_game_annotation_1.csv" # Replace with the file path to any of the video_game_annotation_X.csv files

READ_ONLY_COLUMNS = [0, 1, 2]
ANNOTATION_COLUMNS = [3, 4]

# Replace these paths with actual mapping column name > options file
MAPPING_FIELD_OPTION_PATHS = {
    "genre": "/file/path/to/genre-options.csv",
    "platform": "/file/path/to/platform-options.csv",
}

ONTOLOGY_NAME = "E2E - Tabular Data - Ontology"
OBJECT_NAME = "Game Row"


def parse_csv():
    csv_df = pd.read_csv(TASK_CSV_PATH)
    readonly_columns = csv_df.columns[READ_ONLY_COLUMNS].tolist()
    mapping_columns = csv_df.columns[ANNOTATION_COLUMNS].tolist()

    return mapping_columns, readonly_columns


def create_ontology(text_attribute_names, radio_option_names):
    ontology_structure = OntologyStructure()
    text_object = ontology_structure.add_object(name=OBJECT_NAME, shape=Shape.TEXT)

    for attribute in text_attribute_names:
        text_object.add_attribute(TextAttribute, attribute)

    for column_name in radio_option_names:
        options_path = MAPPING_FIELD_OPTION_PATHS.get(column_name)
        if options_path is None:
            raise ValueError(f"No options file defined for column '{column_name}'")

        options = pd.read_csv(options_path).iloc[:, 0].dropna().astype(str).tolist()

        radio_attribute = text_object.add_attribute(RadioAttribute, column_name, required=True)
        for option in options:
            radio_attribute.add_option(option)

    user_client = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=ENCORD_SSH_KEY,
        domain="https://api.encord.com",
    )
    return user_client.create_ontology(ONTOLOGY_NAME, structure=ontology_structure)


if __name__ == "__main__":
    mapping_columns, readonly_columns = parse_csv()
    ontology = create_ontology(readonly_columns, mapping_columns)
    print(f"Created ontology {ontology.title}, id: {ontology.ontology_hash}")

```

## Create Tabular Data Project

Create a Project adding your Ontology and Dataset for Tabular Data.

<Note>
  * Tabular data currently supports **CONSENSUS** Projects only.
  * An AGENT block must be the first block in the Workflow for Tabular Data Projects.
  * The AGENT block and AGENT pathway **MUST be the exact name** specified below.
</Note>

## Run the Agent script

The `tabular_run_agent.py` populates tasks in the AGENT block in your workflow.

Create the following Python scripts. Both scripts must be in the same directory.

* `tabular_run_agent.py`
* `tabular_utils.py`

After creating the scripts, run the `tabular_run_agent.py` script.

After running the script, tasks that were in the AGENT stage are now in the CONSENSUS - ANNOTATE stage.

<table>
  <thead>
    <tr>
      <th>**Items of Interest**</th>
      <th>**Notes**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`AGENT_STAGE`</td>

      <td>
        Specifies the name of the AGENT block in your Tabular Data Project. This name must exactly match the name of the AGENT block in your Project.
      </td>
    </tr>

    <tr>
      <td>`AGENT_PATHWAY`</td>
      <td>Specifies the name of the Pathway in your AGENT block. This name must exactly match the name of the pathway in the AGENT block in your Project.</td>
    </tr>
  </tbody>
</table>

<CodeGroup>
  ```py tabular_run_agent script theme={"dark"}

  from typing import Annotated
  from pathlib import Path
  import os

  from encord_agents.tasks import Runner
  from encord.objects.ontology_labels_impl import LabelRowV2
  from encord.project import Project
  from encord_agents.tasks.dependencies import dep_asset
  from encord_agents.core.dependencies import Depends
  from encord.objects.common import Shape

  from tabular_utils import parse_csv_and_add_objects

  # --- Configuration ---
  ENCORD_SSH_KEY = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
  PROJECT_HASH = "00000000-0000-0000-0000-000000000000" # Replace with unique Project ID of the tabular data Project
  AGENT_STAGE = "Pre-label"
  AGENT_PATHWAY = "Labelled"

  # Inject into environment so Encord Agents can pick it up
  os.environ["ENCORD_SSH_KEY_FILE"] = ENCORD_SSH_KEY

  runner = Runner(project_hash=PROJECT_HASH)

  @runner.stage(stage=AGENT_STAGE)
  def agent_logic(
      lr: LabelRowV2, project: Project, asset: Annotated[Path, Depends(dep_asset)]
  ):
      ontology = project.ontology_structure
      text_object = ontology.objects[0]
      if text_object is None:
          raise Exception("No objects found")
      elif text_object.shape is not Shape.TEXT:
          raise Exception("Text object required")

      parse_csv_and_add_objects(text_object, lr, asset)

      return AGENT_PATHWAY

  if __name__ == "__main__":
      runner.run()
  ```

  ```py tabular_utils script theme={"dark"}

  import pandas as pd
  from pathlib import Path

  from encord.exceptions import OntologyError
  from encord.objects.attributes import Attribute
  from encord.objects.coordinates import TextCoordinates
  from encord.objects.frames import Range
  from encord.objects.ontology_labels_impl import LabelRowV2
  from encord.objects.ontology_object import Object

  def parse_csv_and_add_objects(
      text_object: Object, label_row: LabelRowV2, asset_link: Path
  ):
      csv_df = pd.read_csv(asset_link)
      filtered_columns = csv_df.columns

      read = None
      with asset_link as f:
          read = f.read_bytes()

      for index, row in csv_df.iloc[0:].iterrows():
          byte_range = get_byte_range_for_row(read, index + 1)
          if byte_range is None:
              raise Exception("Row does not exist")
          (start, end) = byte_range

          row_dict = row[filtered_columns].to_dict()

          add_text_object(text_object, label_row, Range(start=start, end=end), row_dict)

      label_row.save()


  def get_byte_range_for_row(csv_content: bytes, row: int) -> tuple[int, int] | None:
      # Find all newline positions
      newline_positions = []
      current_pos = 0

      while True:
          newline_pos = csv_content.find(b"\n", current_pos)
          if newline_pos == -1:
              break
          newline_positions.append(newline_pos)
          current_pos = newline_pos + 1

      # Check if requested row exists
      if row > len(newline_positions):
          return None

      # Calculate start and end positions
      if row == 0:
          start_byte = 0
      else:
          start_byte = newline_positions[row - 1] + 1

      if row < len(newline_positions):
          end_byte = newline_positions[row]
      else:
          # Last row might not have a trailing newline
          end_byte = len(csv_content)

      return (start_byte, end_byte)


  def add_text_object(
      text_object: Object,
      lr: LabelRowV2,
      byte_range: Range,
      csv_column_to_value: dict[str, str],
  ):
      new_instance = text_object.create_instance()
      new_instance.set_for_frames(coordinates=TextCoordinates(range=[byte_range]))
      for key, value in csv_column_to_value.items():
          try:
              attribute = text_object.get_child_by_title(title=key, type_=Attribute)
              if attribute.required:
                  # If required attribute then this is the one they are writing so ignore
                  continue
              new_instance.set_answer(attribute=attribute, answer=str(value))
          except OntologyError:
              # Ignore columns that don't have attributes
              pass
      lr.add_object_instance(new_instance)

  ```
</CodeGroup>

## Label and Review Tabular Data

**Annotators**

Annotators use drop downs to select the genre and platform for each row.

**Reviewers**

Reviewers verify that the labels are correct.

<Note>Use any column in a row to select correct answers.</Note>

<Tip>
  When there is an issue with labels/classifications, Reviewers can:

  * Reject the task and add a comment about why a task was rejected. Rejected tasks go back to the person who added the labels/classifications.
  * Edit labels directly using the **Edit labels** button and then approve the task.
</Tip>


# User Settings
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-settings-general



To navigate to user settings, click your user icon in the bottom-left of the Encord platform.

<div>
  <img />
</div>

The settings have several tabs:

* **General**: Your user login credentials. Change your password and set up [Multi-Factor Authentication](#multi-factor-authentication) for your Encord user account.
* **[API keys](/platform-documentation/General/general-access-keys)**: creating and managing [SDK](/sdk-documentation/getting-started-sdk/installation-sdk) keys.

## Multi-Factor Authentication

In addition to your login credentials, Encord recommends that you add the alternate SMS verification to receive SMS for OTP while logging in to the Encord platform. You can enroll single or multiple devices for authentication.

1. In the *General* tab, click the **Manage** button under **Multi-factor authentication**.
   The **Enroll new Multi-Factor Authentication** dialog appears.

   <div>
     <img />
   </div>

2. Click one of the following:

   * **Authenticator:**

     a. To configure an authenticator, sign out from Encord.

     b. Log back into Encord.

     c. Navigate back to the *General* tab.

     d. Click the **Manage** button.
     An *Authenticator* configuration dialog appears.

   <div>
     <img />
   </div>

   e. Scan the code using your authenticator app or manually type the string provided into your authenticator app.

   f. Type the code provided by your authenticator app into the dialog.

   g. Click **Enroll**.
   A success dialog appears.

   <div>
     <img />
   </div>

   The next time users sign in, users are required to use an authenticator app to sign in to Encord.

   * **SMS code:**

     a. To configure an SMS code, provide a device name and the phone number that you want to enroll for SMS, and click **Send SMS Code**.

     b. On enrolling a device for the first time, you must sign out and sign in again to authenticate your verification request.

     c. After signing in again, invoke the *Multi-Factor Authentication* modal again from the *General* tab and input your device name and phone number.

     <Note>Only 1 number can be added.</Note>

     <div>
       <img />
     </div>

     d. Click **Send verification code** and solve a CAPTCHA challenge.

     e. In the next field that appears, enter the SMS code received on your phone, and click **Verify SMS Code**.

<Note>To remove a device, click **Manage > Remove**. You must log out and log back in to complete the removal process.</Note>


# Webhooks and Notifications
Source: https://docs.encord.com/platform-documentation/Annotate/annotate-webhooks-notifications



Webhooks are automated requests that send a JSON payload with information about a Project or task to a specified URL at a designated point in your Project's Workflow. For example, if a webhook is added to the *Complete* stage of a Project, then a JSON payload containing the Project and task ID is sent every time a task reaches the *Complete* stage.

<div>
  <iframe />
</div>

Common use-cases for webhooks include:

* [Automatically exporting labels when they are marked as complete](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels#export-labels-to-cloud-storage-recommended).

* Setting up a daily report to track the number of annotation tasks submitted for review each day.

***

## Setting Up Webhooks

Webhooks can be set up when creating or editing a Workflow. This includes setting up a Workflow while creating a new annotation Project, creating a Workflow template, or editing the Workflow of an existing Project.

<Note>Webhooks can only be added to *Annotate* and *Complete* stages. [Webhooks on *Annotate* stages](#task-submitted-payload) trigger when tasks are submitted for review. [Webhooks on *Complete* stages](#task-completed-payload) trigger when a task is completed.</Note>

1. With the Workflow open, click the Workflow stage you want to create a webhook for.
   A pop-up for to configure the Workflow stage appears.

2. In the pop-up, click the *Edit* symbol under the *Webhook* heading.

3. Enter the URL you want the [JSON payload](#webhook-event-payloads) to be sent to. Press <kbd>Enter</kbd> on your keyboard to confirm.

<div>
  <img />
</div>

4. Ensure you save your changes.

<Note>After adding or updating a webhook URL, a unique signing secret is automatically generated for that webhook. This secret appears in the **Signing Secret** section below the URL field and can be used to verify webhook payloads.</Note>

***

## Webhook Event Payloads

### Task Submitted Payload

All task submitted events, triggered on the *Annotate* stage, have the following fields:

| Key                       | Type      | Description                                                                                       |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `uid`                     | `string`  | Unique identifier of the event.                                                                   |
| `version`                 | `integer` | Major version number to indicate backwards incompatible versions.                                 |
| `source`                  | `string`  | The source of the payload. Is always "Encord".                                                    |
| `event_type`              | `string`  | The event type. `task_submitted_event` is triggered on the *Annotate* stage.                      |
| `event_created_timestamp` | `string`  | A string of the timestamp in the ISO 8601 format. For example `2022-04-13T14:35:11.791161+00:00`. |
| `payload`                 | `object`  | An object containing the Project and label information.                                           |
| `project_hash`            | `string`  | The unique identifier for the Project.                                                            |
| `data_hashes`             | `string`  | The unique identifiers for the data unit.                                                         |
| `label_hashes`            | `string`  | The unique identifiers for the Label Row.                                                         |

Example payload:

```json theme={"dark"}
{
  "uid": "687457ce-6489-4891-b7c8-544477d99e41",
  "version": 1,
  "source": "Encord",
  "event_type": "task_submitted_event",
  "event_created_timestamp": "2024-03-25T15:18:55.406529+00:00",
  "payload": {
    "project_hash": "751a3a3e-46b6-4aad-b0b8-19b169f91266",
    "data_hashes": [
      "f0b012de-5aea-4457-b515-936b0c185771"
    ],
    "label_hashes": [
      "fdb9a21f-d9a7-48b5-9dac-dfe3e0e2c57f"
    ]
  }
}
```

### Task Completed Payload

All task completed events, triggered on the *Complete* stage, have the following fields:

| Key                       | Type      | Description                                                                                       |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `uid`                     | `string`  | Unique identifier of the event.                                                                   |
| `version`                 | `integer` | Major version number to indicate backwards incompatible versions.                                 |
| `source`                  | `string`  | The source of the payload. Is always "Encord".                                                    |
| `event_type`              | `string`  | The event type. `task_completed_event` is triggered on the *Complete* stage.                      |
| `event_created_timestamp` | `string`  | A string of the timestamp in the ISO 8601 format. For example `2022-04-13T14:35:11.791161+00:00`. |
| `payload`                 | `object`  | An object containing the Project and label information.                                           |
| `label_hash`              | `string`  | The unique identifier for the Label Row.                                                          |
| `project_hash`            | `string`  | The unique identifier for the Project.                                                            |
| `data_hash`               | `string`  | The unique identifier for the data unit.                                                          |

Example payload:

```json theme={"dark"}
{
  "uid": "950f9048-bd28-42e7-89cb-2538f27c1695",
  "version": 1,
  "source": "Encord",
  "event_type": "task_completed_event",
  "event_created_timestamp": "2024-03-25T15:13:40.456441+00:00",
  "payload": {
    "label_hash": "c25be5c7-2a7f-4de9-8afd-9e2f72064e84",
    "project_hash": "751a3a3e-46b6-4aad-b0b8-19b169f91266",
    "data_hash": "f5fb9c39-cbfc-4bf3-8fdb-95ee4da24c14"
  }
}
```

***

## Verifying Webhook Signatures

Encord signs every webhook request so you can confirm it genuinely originated from Encord and has not been tampered with.

<Info>
  Verification is optional but recommended for production integrations.
</Info>

### How it works

Every webhook request includes two headers:

* `X-Encord-Signature` - an HMAC-SHA256 hex digest of the timestamp and request body, formatted as `{timestamp}.{body}`
* `X-Encord-Timestamp` - a Unix timestamp of when the request was sent

### Retrieving your signing secret

<div>
  <img />
</div>

Open the [**Annotate**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#annotate) or [**Complete**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#complete) Workflow node that contains the webhooks and copy the secret from the **Signing Secret** field. Your signing secret is unique to each webhook URL.

<Note>
  A signing secret is only generated when a valid webhook URL is entered. If you change the webhook URL, a new signing secret is generated.
</Note>

### Managing signing secrets

You can view and copy your signing secret in several ways:

* **In Workflow configuration**: When setting up or editing a webhook in a Workflow stage, the signing secret appears below the URL field with options to show/hide and copy the secret.

* **In webhook management**: From your user settings, you can access all your webhooks and copy their signing secrets using the copy button next to each webhook entry.

<Tip>Use the show/hide toggle to safely view your signing secret without exposing it to others who might be looking at your screen.</Tip>

### Verifying the signature

To verify a request, recompute the signature on your server and compare it against
the `X-Encord-Signature` header.

```python theme={"dark"}
import hashlib
import hmac

def verify_encord_webhook(
    payload_body: bytes,
    signing_secret: str,
    encord_signature: str,
    encord_timestamp: str,
) -> bool:
    message = encord_timestamp.encode() + b"." + payload_body
    expected = hmac.new(
        signing_secret.encode(),
        message,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, encord_signature)
```

If the signatures do not match, discard the request.

### Replay protection

Use the `X-Encord-Timestamp` header to reject requests with a timestamp older than a reasonable threshold (for example, 5 minutes). This prevents replay attacks where a valid request is captured and re-sent.

<Note>
  If no signing secret is configured for a webhook URL, the `X-Encord-Signature` and `X-Encord-Timestamp` headers are not included in the request.
</Note>

***

## IP Addresses for Webhooks

For teams with advanced security practices, you must add our IP addresses to an approved list to ensure that only trusted **incoming** traffic from our services can reach your webhook endpoints.

<Warning>
  US Deployment refers to customers working on Encord's US-hosted instance, rather than simply being located in the United States.
</Warning>

<Tabs>
  <Tab title="Default Deployment (EMEA)">
    * `34.89.106.119/32`
    * `34.142.51.70/32`
  </Tab>

  <Tab title="US Deployments">
    * `34.105.9.215/32`
    * `34.168.169.190/32`
  </Tab>
</Tabs>


# Built-in Agents
Source: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/annotate-agents-catalog-reference



This page lists the **built-in agents** that are available in the **Agents Catalog** and can be added to your projects with minimal configuration.

<Note>Each agent card in the catalog includes a **Learn more** button that opens this documentation page for detailed configuration information.</Note>

## OpenAI Image Description

* **What it does**: Generates a detailed text description of an image using OpenAI vision models.
* **Best for**: Scene descriptions, captions, and summarizing what is happening in an image.
* **Input data**: Image data units.
* **Output**: A single text classification containing the description.
* **Configuration**:

| Parameter         | Description                                                                                                                          | Example                                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model**         | Choose which OpenAI model to use — a faster "mini" model for speed, or a larger model for higher quality at higher cost.             | Use `gpt-4o-mini` for high-volume batch processing, or `gpt-4o` when description accuracy is critical.                                                      |
| **Detail**        | Controls how much visual detail the model sees. Higher detail improves description quality but can increase latency and cost.        | Use `low` for thumbnail images or quick content moderation; use `high` for medical scans or fine-grained scene analysis.                                    |
| **Custom Prompt** | Optional extra instructions that steer the description.                                                                              | `"Focus on the number and position of people in the scene"` for crowd analysis, or `"Describe only the text visible in the image"` for OCR-style summaries. |
| **Temperature**   | Controls how "creative" the wording is. Lower values give more deterministic output; higher values produce more varied descriptions. | Use `0.2` for consistent, factual product descriptions, or `0.8` for diverse creative captions.                                                             |

* **Credentials**: Requires an OpenAI API key.
* **Ontology requirements**: A **classification** with a **TEXT** attribute where the image description is stored.

## Claude Image Description

* **What it does**: Generates a detailed text description of an image using Anthropic Claude vision models.
* **Best for**: Image descriptions where you want to use Claude models.
* **Input data**: Image data units.
* **Output**: A single text classification containing the description.
* **Configuration**:

| Parameter         | Description                                                                                             | Example                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Model**         | Choose which Claude model to use. Larger models provide better quality at higher cost.                  | Use `claude-haiku-4-5` for fast, high-volume pipelines, or `claude-opus-4-6` when description quality is the priority.               |
| **Custom Prompt** | Optional extra instructions to emphasize what matters in the description.                               | `"Focus on visible defects or damage"` for quality control, or `"Describe the background environment only"` for scene context tasks. |
| **Temperature**   | Controls variation in the output. Lower values make descriptions more consistent across similar images. | Use `0.1` for repeatable, audit-friendly descriptions, or `0.7` for more expressive captions in creative workflows.                  |

* **Credentials**: Requires an Anthropic API key.
* **Ontology requirements**: A **classification** with a **TEXT** attribute where the image description is stored.

## Classify an Image

* **What it does**: Classifies images into one or more ontology categories using OpenAI vision models.
* **Best for**: Category or label assignment, such as object presence, scene type, or attributes.
* **Input data**: Image data units.
* **Output**: A classification answer using your ontology options (single- or multi-select).
* **Configuration**:

| Parameter         | Description                                                                                                                                                | Example                                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model**         | Choose the OpenAI model used to make classification decisions. Smaller models are cheaper and faster; larger models handle more nuanced categories.        | Use `gpt-4o-mini` for straightforward labels like `indoor`/`outdoor`, or `gpt-4o` for fine-grained distinctions like similar product subtypes. |
| **Detail**        | Controls how much visual information the model receives. Higher detail helps with fine-grained distinctions.                                               | Use `low` for broad scene classification; use `high` when distinguishing visually similar product types or detecting small objects.            |
| **Custom Prompt** | Optional guidance that explains how the model should interpret your ontology, such as definitions of borderline classes.                                   | `"If both a person and a vehicle are present, select both labels"` or `"Classify as 'damaged' only if defects are clearly visible"`.           |
| **Temperature**   | Controls how confidently the model sticks to the most likely class vs. exploring alternatives. Lower values are recommended for production classification. | Use `0.0`–`0.2` for consistent, production-grade labeling, or `0.6` when stress-testing edge cases during evaluation.                          |

* **Credentials**: Requires an OpenAI API key.
* **Ontology requirements**: A **classification feature with options**, using **radio** (single-select) or **checklist** (multi-select).

## Ask a Question About an Image

* **What it does**: Answers a natural-language question about an image (visual question answering).
* **Best for**: Targeted questions such as "What brands are visible?" or "What are the people doing?"
* **Input data**: Image data units.
* **Output**: A single text classification containing the answer.
* **Configuration**:

| Parameter       | Description                                                                                                           | Example                                                                                                                                                                                |
| --------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model**       | Choose which OpenAI model should answer the question. Use larger models for more complex or nuanced questions.        | Use `gpt-4o-mini` for simple factual questions like `"Is the light on or off?"`, or `gpt-4o` for questions requiring reasoning like `"Is the safety equipment being used correctly?"`. |
| **Question**    | The natural-language question you want to ask about each image.                                                       | `"How many people are in this image?"`, `"What brand logos are visible?"`, or `"Is the safety helmet worn correctly?"`.                                                                |
| **Detail**      | Controls how much visual detail the model considers when answering. Higher detail helps with dense or complex scenes. | Use `low` for simple presence/absence questions; use `high` for questions about small text, crowded scenes, or fine-grained object attributes.                                         |
| **Temperature** | Controls how deterministic the answers are. Lower values reduce variability between similar images.                   | Use `0.0` for consistent yes/no or count-based answers, or `0.5` for more descriptive open-ended responses.                                                                            |

* **Credentials**: Requires an OpenAI API key.
* **Ontology requirements**: A **classification** with a **TEXT** attribute where the answer is stored.

## Transcribe Audio

* **What it does**: Transcribes entire audio files using OpenAI Whisper into a single transcript.
* **Best for**: Full-file audio transcription (calls, interviews, long recordings) where you want one combined transcript.
* **Input data**: Audio data units.
* **Output**: A single text classification containing the full transcript.
* **Configuration**:

| Parameter    | Description                                                                                         | Example                                                                                                                                       |
| ------------ | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model**    | Select which Whisper model version to use. Larger models may improve accuracy on challenging audio. | Use `whisper-1` for clean, studio-quality recordings, or a larger variant for heavily accented speech or noisy environments.                  |
| **Language** | Optionally specify the spoken language to improve accuracy; leave blank to let Whisper auto-detect. | Set `en` for English-only call center recordings, or leave blank for multilingual interview datasets.                                         |
| **Prompt**   | Optional context to bias the transcript toward domain-specific terms or acronyms.                   | `"This is a medical consultation. Terms include ECG, systolic, and triage."` or `"Speaker discusses cloud services: AWS, Kubernetes, CI/CD."` |

* **Credentials**: Requires an OpenAI API key.
* **Ontology requirements**: A **classification** with a **TEXT** attribute where the transcript is stored.

## Diarize and Transcribe Audio

* **What it does**: Transcribes audio and performs two-speaker diarization, writing separate transcripts per speaker.
* **Best for**: Two-speaker conversations (for example, agent/customer) where you want per-speaker transcripts.
* **Input data**: Audio data units.
* **Output**:
  * Time-based **AUDIO objects** for Speaker 1 and Speaker 2 segments.
  * **TEXT attributes** on those objects with each speaker's transcript.
* **Configuration**:
  * **Language**: Optionally specify the language spoken in the audio. This can improve diarization and transcription quality; leave blank to auto-detect.
* **Credentials**: Requires an OpenAI API key.
* **Ontology requirements**:
  * An **AUDIO object** for Speaker 1 segments, plus a **TEXT attribute** on that object.
  * An **AUDIO object** for Speaker 2 segments, plus a **TEXT attribute** on that object.

## Recognize and Extract Text

* **What it does**: Detects and extracts text from images using Google Document AI, returning polygon regions and associated text.
* **Best for**: OCR on documents, receipts, forms, and other scanned images where you need both text and its region.
* **Input data**: Image data units.
* **Output**:
  * **POLYGON objects** for each detected text region.
  * A **TEXT attribute** on each polygon containing the extracted text.
* **Configuration**:

| Parameter              | Description                                                                                                                | Example                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Processor ID**       | Identifies which Document AI processor to use, determining the underlying OCR model and configuration in your GCP project. | `abc123def456` — the ID found on your processor's details page in the Google Cloud Console. |
| **Processor location** | Region where the processor is hosted. Should match the region where you created the processor.                             | `us` for processors created in the United States, or `eu` for processors created in Europe. |
| **Language hints**     | Optional list of likely languages in your documents to improve OCR accuracy.                                               | `["en"]` for English-only invoices, or `["en", "fr"]` for bilingual Canadian documents.     |

* **Credentials**: Requires a Google Document AI service account.
* **Ontology requirements**:
  * A **POLYGON object** type for OCR regions.
  * A **TEXT attribute** attached to that polygon object for the extracted text.


# Agents Overview
Source: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/annotate-agents-overview



Agents are automated models that run on your data within Encord — pre-labeling assets, reviewing annotations, or performing custom actions.

## Agent Catalog

The **Agents Catalog** is the central place to discover, configure, and deploy agents in Encord — from off-the-shelf integrations to fully [Custom Agents](/platform-documentation/Annotate/automated-labeling/annotate-custom-agents).

<div>
  <img />
</div>

## Agent Types

* **Catalog agents**: Built-in agents that you configure in a few simple steps (for example, OpenAI or Google Document AI). See [available Agents](/platform-documentation/Annotate/automated-labeling/annotate-agents-catalog-reference) for a full list.
* **Custom agents**: Configured using the **Agents Catalog**. See [Custom Agents](/platform-documentation/Annotate/automated-labeling/annotate-custom-agents) for details.

## Enable Agents

1. Navigate to **Agents** in the left-hand navigation. The **Agents catalog** tab opens by default.
2. Browse or search for agents:
   * Built-in agents are shown as tiles you can configure with API keys and simple options.
   * The **Custom agent** tile lets you register your own HTTPS endpoint as an agent.
   * A **Request agent** tile lets you ask Encord to add a new integration.
3. Click **Add** to enable an agent.
4. Give the Agent a meaningful name.
5. Add [Ontology and label target](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview#ontology-%26-label-targets) information, and any [required external credentials](#external-credentials) if necessary.
6. Click **Add agent** to save the configuration and enable the agent for use in your Projects.

<div>
  <img />
</div>

### External Credentials

Many catalog agents require **external credentials**, such as OpenAI API keys or Google service accounts.

You can add and manage these credentials in two ways:

* **While creating an agent**: When you configure a catalog agent, you can choose or create the required external credential directly in the form.
* **From workspace settings**: Go to **Workspace settings** > **External credentials** to create, reuse, or revoke credentials across agents.

Once configured, credentials can be reused by multiple agents without re-entering secrets.

### Ontology & Label Targets

* **Ontology** - The Ontology the Agent uses.
* **Label Targets** - The specific classes within the Ontology that the Agent writes its output to. Only classes that the Agent template supports as outputs are available for selection.

<Info>
  The Agent can only be attached to projects that use the same Ontology. When creating an Agent directly from a Workflow stage, the Project's Ontology is pre-filled automatically.
</Info>

### Repeatable Ontology Feature Requirements

Some agent templates declare one or more Ontology feature requirements as **repeatable**. A repeatable requirement lets you assign multiple Ontology features to a single role. For example, selecting several source object classes for an agent that merges or compares multiple class types simultaneously.

When a requirement is repeatable, the agent configuration form displays a **multi-select picker** instead of the standard single-select dropdown. You can search and select as many eligible features as the template allows.

**Validation rules for repeatable requirements:**

* The template defines a minimum number of features you must select (default: 1). The form prevents submission until this minimum is met.
* If the template defines a maximum, the picker disables further selection once you reach that limit.

**How repeatable features appear in the agent detail view:**

When you view a configured agent, multiple features assigned to a repeatable role are grouped under a single label. For example, an agent with three source classes displays as:

> **Source Object Classes:** \[ClassA] \[ClassB] \[ClassC]

**Ontology compatibility:**

When selecting an Ontology for an agent with repeatable requirements, Encord automatically excludes ontologies that do not contain enough eligible features to satisfy the minimum selection count for each repeatable requirement.

<Note>
  Auto-selection of the sole eligible feature — which applies to standard single-select requirements — does not apply to repeatable requirements. You must make your selections manually.
</Note>


# Running Agents
Source: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/annotate-agents-usage



There are two ways to run Agents in Encord:

* **In the Label Editor**: The Agent is triggered on demand by the Tasker while annotating or reviewing a task.
* **From your Workflow**: The Agent is triggered on tasks that pass through the Workflow node.

## In the Label Editor

All agents created via the Agents Catalog (built-in and custom) are triggered in the same way from the Label Editor:

1. Open the data item in the Label Editor.
2. Right-click in the editor canvas, choose **Trigger agent**, and select the agent you want to run.

<div>
  <img />
</div>

## In the Workflow

Agents can be added as a Workflow node when creating or editing a Workflow. When the Workflow runs, the Agent is triggered for all tasks that pass through that node.

1. Drag the **Agent** node in the Workflow editor onto the canvas and connect it to the desired nodes.

<div>
  <img />
</div>

2. Click the **Agent** node.
3. Click the **+** to add a new Agent, or the dropdown to select an existing enabled Agent.

<div>
  <img />
</div>

4. Click **Run** next to a task to run the Agent on a specific task to verify the output is as expected.

5. Click **Go live** to automatically run the Agent on tasks that pass through this node in the Workflow.

<Info>
  Agent activity can be monitored in the **Analytics** dashboard. See [Analytics for Agents](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#agents) for details.
</Info>

<div>
  <img />
</div>

<Note>
  If you do not have access to the Ontology required by an Agent, you see an error message with an option to join the Ontology, if you're an Org Admin.
</Note>

### Decision Pathways

Some Agents are built on templates that define a fixed set of possible decisions — for example, `accept`, `reject`, and `needs_review`. When you select one of these Agents in the Workflow builder, Encord automatically populates the Agent node with one named pathway per decision, replacing the default single pathway.

**How decision pathways work:**

* When you select a decision-routing Agent from the dropdown in the Agent node panel, the node's pathways update automatically to reflect the decisions defined by the Agent's template.
* A **Decision pathways** section appears in the Agent panel, listing each pathway name and its ID.
* Each pathway acts as a separate exit handle on the Agent node that you can connect to a downstream Workflow stage.
* If you switch to a different Agent that does not use decision routing, the pathways reset to a single default pathway.

<Tip>Use the pathway IDs listed in the **Decision pathways** panel to identify and wire each exit to the correct downstream node — for example, connecting `accept` to a Review stage and `reject` to Complete.</Tip>

To connect decision pathways to downstream nodes:

<Steps>
  <Step title="Add an Agent node to the Workflow">
    Drag the **Agent** node onto the Workflow canvas and connect it to the desired upstream node.
  </Step>

  <Step title="Select a decision-routing Agent">
    Click the **Agent** node to open the panel, then select a decision-routing Agent from the dropdown. The node updates to display one exit handle per decision.
  </Step>

  <Step title="Review the Decision pathways panel">
    In the **Decision pathways** section of the panel, review the list of named pathways and their IDs.
  </Step>

  <Step title="Connect each pathway to a downstream node">
    Drag each named pathway handle on the Agent node to the appropriate downstream Workflow stage.
  </Step>
</Steps>

### Agent Task Management

When viewing an Agent stage, the Queue displays additional controls and status information for Workflow agents.

**Agent Status Banner**

For Agent stages, a status banner appears above the task list showing the agent name and icon (click to view detailed agent configuration), a status indicator showing whether the agent is Live (green) or Paused (orange), and control buttons that Admins and Team Managers can use to pause/resume agents or view agent settings.

**Agent Controls**

<Note>Only Workspace and Project Admins and Team Managers can control agent execution.</Note>

| Action                | How                                                                    |
| --------------------- | ---------------------------------------------------------------------- |
| Pause agent           | Click **Pause** to stop automatic processing                           |
| Resume agent          | Click **Go live** to resume automatic processing                       |
| Manual task execution | Navigate to paused agent stage → find **Pending** task → click **Run** |
| Retry failed task     | Find **Failed** task → click **Retry**                                 |

<Tip>Use manual execution when testing agent configurations or troubleshooting specific data units before resuming live processing.</Tip>

**Agent Execution Status**

For Projects using Agents in their Workflow, tasks display execution status badges showing the current state of automated processing:

| Status     | Description                                                               |
| ---------- | ------------------------------------------------------------------------- |
| Pending    | The agent execution is queued and waiting to start.                       |
| Dispatched | The agent execution has been assigned to a worker.                        |
| Running    | The agent is currently processing the task.                               |
| Succeeded  | The agent execution completed successfully.                               |
| Failed     | The agent execution encountered an error and failed to complete.          |
| Timed out  | The agent execution exceeded the maximum allowed time and was terminated. |
| Canceled   | The agent execution was manually canceled before completion.              |

**Retry Failed Tasks**

You can retry tasks that failed or timed out by selecting one or more affected tasks in the Queue, then clicking Retry failed to re-run the agent on those tasks. The system will attempt to execute the Agent again on the selected tasks.

<Note>The Retry failed button is only available for Agent stages with catalog agents and only appears when you have selected tasks that failed or timed out.</Note>

**Moving Agent Tasks**

When moving agent tasks to the next stage, the system skips tasks that are currently running or dispatched (they remain in the current stage), only moving tasks that are not actively being processed. A confirmation dialog will show how many tasks are moved and how many are skipped.

<Warning>Tasks that are currently running or dispatched cannot be moved and remain in their current stage until execution completes.</Warning>

## Creating Projects with Agent Stages

When creating a new Project that includes an Agent stage, you must be a member of the Agent's associated Ontology. If you are not a member of the required Ontology, the **Create project with agent stage** button is disabled.

<Note>If you see a disabled **Create project with agent stage** button with a tooltip message, you need to join the Agent's ontology before you can create a project using that Agent.</Note>

To resolve this:

1. Contact your Workspace Admin or Ontology owner to request access to the required Ontology.
2. Once you have been added as a member of the Ontology, the **Create project with agent stage** button becomes available.
3. Create the Project with the Agent stage included.

## Repeatable Ontology Feature Requirements

Some agent templates support **repeatable** ontology feature requirements. A repeatable requirement allows you to select multiple ontology features for a single role — for example, selecting several source object classes for an agent that merges object classes.

### Identifying repeatable requirements

When configuring an agent whose template includes a repeatable requirement, the feature selector for that role displays a **multi-select tree picker** instead of the standard single-select dropdown. You can search and select multiple features from your ontology within the same field.

### Selection validation

Repeatable requirements enforce minimum and maximum selection counts:

* **Minimum selections**: You must select at least the required number of features before you can submit the agent configuration. If you have not met the minimum, the form displays a validation message such as "Please select at least N features."
* **Maximum selections**: When a maximum is configured, the picker prevents additional selections once you reach the limit.

<Note>The minimum and maximum counts are defined by the agent template. If no maximum is set, you can select as many eligible features as your ontology contains.</Note>

### Ontology compatibility

When selecting an ontology during agent creation, Encord automatically filters out ontologies that do not contain enough eligible features to satisfy the minimum count for any repeatable requirement. Only compatible ontologies appear in the selector.

### Viewing repeatable features in the agent detail

In the agent detail view, multiple features selected for a repeatable requirement are displayed grouped under a single role label. For example, if you selected three source object classes, the detail view shows:

**Source Object Classes:** \[ClassA] \[ClassB] \[ClassC]

This grouped display replaces the previous behavior of showing separate rows with indexed suffixes.


# Custom Agents Overview
Source: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/annotate-custom-agents



Custom agents let you plug your own HTTPS endpoints into Encord and trigger them in the Label Editor, or as part of your Workflow.

## Custom Agents in the Agents Catalog

<Note>Only HTTPS endpoints are supported for Custom Agents.</Note>

**To register a Custom Agent using the Agents Catalog:**

1. Go to **Agents** in the left-hand navigation.
2. In the **Agents catalog** tab, select the **Custom agent** tile.

<div>
  <img />
</div>

3. Fill in the form:
   * Give the agent a clear name and description.
   * Provide the public HTTPS endpoint that Encord should call.
   * Enter possible decisions that the agent can return (for example, "approve" or "reject"). These decisions are represented as pathways in the Workflow. If your agent does not return decisions, you can leave this field blank.
4. Save the configuration to register the Custom Agent.

## Setting Up Custom Agents

<Tip>
  For end-to-end examples (including example payloads and code), visit our [Agents documentation here](/agents-documentation/Basics/Installation).
</Tip>

Before you can register a Custom Agent, you must create and host the HTTPS endpoint that acts as your agent.

At a high level, your backend should:

* Accept a JSON payload from Encord describing the current project, data item, and frame.
* Use the Encord SDK or API (and any external models you choose) to perform work.
* Write results back to Encord (for example, updating labels or classifications).
* Return a successful HTTP status code so the editor knows the request completed.

Once saved, the agent appears in the **Enabled** tab of the Agents section.

## Testing Custom Agent Endpoints

<Note>You can test your custom agent endpoint directly from the Encord platform to verify it's working correctly before using it in production.</Note>

After registering your Custom Agent, you can test its endpoint:

1. Navigate to your agent in the **Enabled** tab.
2. Click the **Test** tab in the agent details page.
3. Configure the test payload with sample data (project hash, data hash, and frame number).
4. Click **Test agent** to send a request to your endpoint.

The test sends requests directly from your browser to your endpoint. Your agent must allow CORS requests from the Encord domain (e.g., [https://app.encord.com](https://app.encord.com)) for testing to work. If your agent restricts access by source IP, you must allow your current IP address for testing.

<Warning>A successful test from your browser does not guarantee that Encord's servers can reach your endpoint. Ensure your endpoint is accessible from Encord's infrastructure for production use.</Warning>

## Using Custom Agents

The Agent is triggered:

* **In the Label Editor**: On demand by the Tasker while annotating or reviewing a task. [See here](/platform-documentation/Annotate/automated-labeling/annotate-agents-usage#in-the-label-editor) for more information.

* **From your Workflow**: On tasks that pass through the Workflow node. Custom agents are triggered in the same way as other Agents. [Click here to learn more](/platform-documentation/Annotate/automated-labeling/annotate-agents-usage).

## Custom Workflow Agents - Manual

If your custom agent should be triggered manually, open the **Advanced** tab in the Agent node configuration to set them up. Tasks in this Agent stage do not proceed through the workflow unless the agent is triggered manually.

When setting up an agent as "advanced", you do not directly assign a custom agent. Instead, you are hosting a service that picks up tasks from the Workflow stage, performs an action, and then progresses the task to the next stage.

<div>
  <img />
</div>

### Configure batched webhook notifications

You can add a webhook to an Advanced Agent stage so your service can learn when tasks are waiting without continuously polling Encord. The signed notification contains no task data; after receiving it, fetch the Agent stage queue with the SDK.

1. In the Workflow, select the Agent stage and choose **Advanced**.
2. Under **Webhook**, click the edit icon, enter your endpoint URL, and press <kbd>Enter</kbd>.
3. Under **Batching**, set the **Batch size** and **Maximum wait (minutes)**. Encord checks the queue every five minutes and notifies your endpoint when the number of waiting tasks reaches the batch size or a task exceeds the maximum wait. The defaults are 1 task and 30 minutes.
4. Save the Workflow. You can use the generated **Signing secret** to [verify webhook signatures](/platform-documentation/Annotate/annotate-webhooks-notifications#verifying-webhook-signatures).

Removing the webhook URL also removes its batching settings. Switching the Agent stage to **Auto** removes the webhook configuration.

### Examples

Use the Encord SDK to configure your Advanced Custom Agent. The Agent executes the configured SDK script for all tasks that are routed through the Agent stage in your Workflow.

<AccordionGroup>
  <Accordion title="General Example">
    The General Example script shows how to configure a Workflow Agent with the name `Agent 1` and with a pathway called `continue to Review`.

    <Tip>Agent nodes can be used in conjunction with bundles to [efficiently handle bulk actions](/sdk-documentation/general-sdk/sdk-bulk-action-best-practices)</Tip>

    Ensure that you:

    * Replace `<private_key_path>` with the path to your private key.
    * Replace `<project_hash>` with the hash of your Project.
    * Insert your custom logic where the comment instructs you to do so.

    ```python General Example theme={"dark"}
    # Import dependencies
    from encord.user_client import EncordUserClient
    from encord.workflow import AgentStage

    # 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 that contains the agent. Replace <project_hash> with the hash of your Project
    project = user_client.get_project(<project_hash>)

    # Specify the Agent
    agent_stage = project.workflow.get_stage(name="Agent 1", type_=AgentStage)
    for task in agent_stage.get_tasks():

        # Now you have the agent task containing the data hash
        # Insert you custom logic here

    # When the custom logic is completed, the task can be moved forward to the selected pathway
    task.proceed(pathway_name="continue to Review")
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Pre-Classification of Images Using GPT 4o">
    ```mermaid theme={"dark"}
     sequenceDiagram
     participant AWS as AWS (Image Storage)
     participant Encord as Encord (Project)
     participant Agent as Agent Node (In Encord)
     participant Server as Your Server
     participant OpenAI as OpenAI

     AWS->>Encord: Send Signed Image URLs
     Encord->>Agent: Add Signed Image URL to Agent node
     Agent->>Server: Send Signed Image URL
     Server->>OpenAI: Send Image Data + Prompt
     OpenAI-->>Server: Return Classification
     Server->>Server: Transform Classification to Encord label structure
     Server->>Agent: Save Labels to Encord
     Agent->>Encord: Classification Saved to Label Row
     Encord->>Encord: Task Moved to Annotation Stage
    ```

    <Note> See our [end-to-end guide](/agents-documentation/Task-Agents/GPT4PreClassificationImages) for Pre-Classification using GPT 4o for more detailed information.</Note>

    The Pre-Classification script uses GPT 4o mini to route images to different annotation stages depending on what it is contained in the image. The Pre-Classification script applies to the following Workflow.

    <div>
      <img />
    </div>

    <Tip>Agent nodes can be used in conjunction with bundles to [efficiently handle bulk actions](/sdk-documentation/general-sdk/sdk-bulk-action-best-practices)</Tip>

    In the following script:

    * Replace `<private_key_path>` with the hash of your private key.
    * Replace `<project_hash>` with the hash of your Project.
    * Replace `Agent 1` with the name of your Agent stage.

    <CodeGroup>
      ```python Pre-Classification for Images Example theme={"dark"}
      # Import dependencies
      from encord.user_client import EncordUserClient
      from encord.workflow import AgentStage
      import openai
      import base64
      import requests
      import json

      # Initialize your OpenAI client
      openai.api_key = "<your_openai_api_key>"

      def get_classification_from_the_model(media_content):
          """
          Example function that passes media to OpenAI's ChatGPT API along with the prompt
          and parses the result.
          """
          prompt = """
          You are an image analysis expert. You're working on a project that includes annotation of different pets images.
          Your task is to assign one of the following tags to the image: "cat", "dog", "other".

          Reply in JSON format of the following structure: { "classification": cat|dog|other }
          """

          completion = openai.ChatCompletion.create(
              model="gpt-4o-mini",
              messages=[
                  ChatCompletionSystemMessageParam(role="system", content=prompt),
                  ChatCompletionUserMessageParam(
                      role="user",
                      content=[
                          ChatCompletionContentPartImageParam(
                              image_url=ImageURL(url=f"data:image/jpeg;base64,{media_content}", detail="auto"),
                              type="image_url",
                          )
                      ]
                  ),
              ],
              response_format=ResponseFormat(type="json_object"),
              max_tokens=1000,
          )

          raw_text_completion = completion.choices[0].message.content
          try:
              parsed_result = json.loads(raw_text_completion)
              return parsed_result["classification"].lower()
          except Exception as e:
              print(f"Failed to process the model response: {e}")
              return None


      # 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 that contains the agent. Replace <project_hash> with the hash of your Project
      project = user_client.get_project("<project_hash>")

      radio_classification = project.ontology_structure.get_child_by_title(
      title="Animal",
      type_=Classification,
      )

      cat_option = radio_ontology_classification.get_child_by_title(
      title="Cat", type_=Option
      )

      dog_option = radio_ontology_classification.get_child_by_title(
      title="Dog", type_=Option
      )

      # Specify the Agent
      agent_stage = project.workflow.get_stage(name="Agent 1", type_=AgentStage)

      for task in agent_stage.get_tasks():
          # Got a task for the following data unit
          print(f"{task.data_hash} -> {task.data_title}")

          # Getting a label row for the data unit
          label_row = project.list_label_rows_v2(data_hashes=[task.data_hash])[0]
          label_row.initialise_labels(include_signed_url=True)

          # Downloading the media:
          media_response = requests.get(label_row.data_link)
          media_content = base64.b64encode(media_response.content).decode("utf-8")

          # Now we can send the media to OpenAI:
          model_response = get_classification_from_the_model(media_content)

          # And interpret the result:
          match model_response:
              case "cat":

                  # Create a classification instance
                  classification_instance = (
                      radio_ontology_classification.create_instance()
                  )

                  radio_classification_instance.set_answer(
                      answer=cat_option
                  )
                  
                  label_row.add_classification_instance(radio_classification_instance)
                  label_row.save()

                  task.proceed(pathway_name="Cat")
              case "dog":

                  # Create & save classification instance
                  classification_instance = (
                      radio_ontology_classification.create_instance()
                  )
              
                  radio_classification_instance.set_answer(
                      answer=dog_option
                  )

                  
                  label_row.add_classification_instance(radio_classification_instance)
                  label_row.save()

                  task.proceed(pathway_name="Dog")
              case _:
                  task.proceed(pathway_name="Other")
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Pre-Labeling Videos Using a Mock Model">
    <Warning>
      This guide makes the following assumptions:

      * You have a model that takes video frames as an input and provides bounding box coordinates and confidence scores as an output.
      * You have installed the `encord-agents` library using the following command:

      ```
      python -m pip install encord-agents
      ```
    </Warning>

    The Pre-Labeling Script selects a random class from the Ontology, generates random bounding box labels, and applies random confidence scores for video frames before advancing the videos to the annotation stage (`Annotate 1`). Below is an example of a Workflow where the Pre-Labeling agent can be effectively utilized.

    <div>
      <img />
    </div>

    <Warning>
      To authenticate, you must set either of following environment variables in the environment that you plan to run your agents.

      * ENCORD\_SSH\_KEY: Containing the raw private key file content
      * ENCORD\_SSH\_KEY\_FILE: Containing the absolute path to the private key file
    </Warning>

    In the following script:

    * Replace `<project_hash>` with the hash of your Project.
    * Replace the mock model with your own model, and adapt the rest of the script according to your needs.
    * If you choose to give your python file a different name, ensure you replace all references to `prelabel_video.py` with your new file name.

    ```python prelabel_video.py theme={"dark"}
    #Import Dependencies
    import random
    from dataclasses import dataclass
    from typing import Iterable

    import numpy as np
    from encord.objects.coordinates import BoundingBoxCoordinates
    from encord.objects.ontology_labels_impl import LabelRowV2
    from encord.project import Project
    from encord_agents.core.data_model import Frame
    from encord_agents.tasks import Depends, Runner
    from encord_agents.tasks.dependencies import dep_video_iterator
    from numpy.typing import NDArray
    from typing_extensions import Annotated


    # Set the Environment variable to authenticate with Encord
    ENCORD_SSH_KEY_FILE="/path/to/file/" prelabel_video.py

    runner = Runner(project_hash="<project_hash>")

    # === BEGIN MOCK MODEL === #
    @dataclass
    class ModelPrediction:
        label: int
        coords: BoundingBoxCoordinates
        conf: float


    def fake_predict(image: NDArray[np.uint8]) -> list[ModelPrediction]:
        return [
            ModelPrediction(
                label=random.choice(range(3)),
                coords=BoundingBoxCoordinates(
                    top_left_x=random.random() * 0.5,
                    top_left_y=random.random() * 0.5,
                    width=random.random() * 0.5,
                    height=random.random() * 0.5,
                ),
                conf=random.random() + 0.5,
            )
            for _ in range(10)
        ]


    model = fake_predict
    # === END MOCK MODEL === #

    @runner.stage(stage="Pre-Labeling Agent")
    def run_something(
        lr: LabelRowV2,
        project: Project,
        frames: Annotated[Iterable[Frame], Depends(dep_video_iterator)],
    ) -> str:
        ontology = project.ontology_structure

        # Create an object instance for each frame in the video and save the labels. 
        for frame in frames:
            outputs = model(frame.content)
            for output in outputs:
                ins = ontology.objects[output.label].create_instance()
                ins.set_for_frames(
                    frames=frame.frame, coordinates=output.coords, confidence=output.conf
                )

                lr.add_object_instance(ins)

        lr.save()

        # Return the name of the stage the task should progress to
        return "Annotate 1"  


    if __name__ == "__main__":
        runner.run()
    ```
  </Accordion>
</AccordionGroup>

## Repeatable Ontology Feature Requirements

Some agent templates support **repeatable** Ontology feature requirements, which allow you to assign multiple ontology features to a single role. This is useful for agents that need to operate across several classes simultaneously, for example, a merge-object-classes agent that combines multiple source classes into one.

### Selecting features for a repeatable requirement

When an agent template declares a requirement as repeatable, the configuration form displays a **multi-select tree picker** instead of the standard single-select picker.

<Note>The multi-select tree picker only appears for requirements that the agent template has marked as repeatable. Requirements that are not repeatable continue to use the standard single-select behavior.</Note>

* Select as many Ontology features as the requirement allows by clicking each feature in the tree picker.
* The form enforces a **minimum** number of selections. You cannot submit the form until you have selected at least the required number of features. If you select too few, the form displays the message: *"Please select at least N features"*.
* If the template defines a **maximum** number of selections, the picker prevents you from selecting additional features once the maximum is reached.

### How selected features appear in the agent detail view

After you save the agent, the detail view groups all features selected for a repeatable requirement under a single label. For example, if you selected **ClassA** and **ClassB** for a role called **Source Object Classes**, the detail view displays:

**Source Object Classes:** `ClassA` `ClassB`

### Ontology compatibility and repeatable requirements

When you select an ontology during agent creation, Encord automatically filters out ontologies that do not contain enough eligible features to satisfy the minimum selection count for any repeatable requirement. Only ontologies with a sufficient number of matching features appear in the Ontology selector.

## End-to-End Agent Examples

We provide end-to-end examples of custom agent implementation using Jupyter Notebooks [here](/agents-documentation/Task-Agents/Task-Agent-Examples).


# Interpolation
Source: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/annotate-interpolation



Interpolation is a process to automatically create instance labels by estimating the location that labels should be created in videos and image sequences. Interpolation uses manual labels as reference points and needs to be run separately for each object instance.

<Note>
  [Object tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam) and interpolation both automatically apply labels.

  * Interpolation **applies labels in between existing labels**.
  * [Object tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam) uses SAM 2 and applies labels to consecutive frames.
</Note>

All labels automatically created using interpolation are assigned a [confidence score (α)](/platform-documentation/Annotate/annotate-label-editor#confidence-score) of 99%.

<Note>No data is stored on our servers when using interpolation.</Note>

***

### Ontologies

| **Ontology shape**     | **Interpolation** | **Tracking** |
| ---------------------- | ----------------- | ------------ |
| Bounding box           | ✅                 | ✅            |
| Rotatable bounding box | ✅                 | ✅            |
| Polygon                | ✅                 | ❌            |
| Polyline               | ✅                 | ✅            |
| Primitive              | ✅                 | ✅            |
| Keypoint               | ✅                 | ✅            |
| Bitmask                | ✅                 | ❌            |

***

#### Simple Interpolation

The video tutorial below goes through the basics of using interpolation in the Label Editor.

<div>
  <iframe />
</div>

1. Create instance labels on at least two non-consecutive frames.

<Tip>The more instance labels are manually added throughout the video, the more accurate the resulting interpolation becomes. </Tip>

2. Click the three dots icon on the instance to be interpolated, and click **Interpolate**.

<div>
  <img />
</div>

3. Interpolation is run between the first and last frames the instance is labeled.

#### Keyboard Shortcut

You can use keyboard shortcuts to run interpolation.

1. Click the instance label.
2. Use the <kbd>Shift</kbd> + <kbd>I</kbd> keyboard shortcut to the run interpolation between the first and last frames the instance is labeled.

### Advanced Interpolation

1. Create instance labels on at least two non-consecutive frames.

<Tip>Increase the accuracy of interpolated labels by adding more manual instance labels to different frames as references. </Tip>

2. Click the **Automated labelling** button in the bottom left corner of the label editor to bring up the options for automated labeling. The *Tracking and interpolation* section is open by default.

3. The *Tracking and interpolation* section is open by default.
   * Select *Interpolation* under the *Method* heading.
   * Select the object instance(s) you want to interpolate.
   * *Interpolation range* specifies the range of frames for interpolation.

<Note>Only Workspaces on ['Enterprise' pricing](https://encord.com/pricing/) can interpolate over a range larger than 1000 frames.</Note>

4. Click **Run interpolation** to interpolate the selected object instances.

<div>
  <img />
</div>

***

### Re-Interpolate

Interpolation results can be improved by manually correcting some interpolated labels, and re-running the interpolation.

Enable the *Interpolation auto adjustments* toggle in the *Drawing settings* section of the label editor settings. This ensures that only labels with a [confidence score (α)](/platform-documentation/Annotate/annotate-label-editor#confidence-score) less than 100% are overwritten in successive interpolations, while manual labels (α = 100%) are kept and serve as key frames.

<div>
  <img />
</div>

***

<div>
  <img />
</div>

This process can be repeated any number of times.

<Note>All labels created using interpolation are always assigned α = 99%.</Note>


# SAM Segmentation & Tracking
Source: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/annotate-sam



Segment Anything Model (SAM) allows you to automatically create labels around distinct features in all supported file formats.

<Info>
  * SAM 2 is used for tracking.
  * SAM 3 is used for labeling objects
</Info>

***

## Segmentation

### Availability

| Ontology Shape         | Supported? |
| ---------------------- | ---------- |
| Polygon                | ✅          |
| Bounding box           | ✅          |
| Bitmask                | ✅          |
| Rotatable bounding box | ✅          |
| Keypoint               | ❌          |
| Polyline               | ❌          |
| Object Primitive       | ❌          |

| Modality       | Supported |
| -------------- | --------- |
| Single Image   | ✅         |
| Image Group    | ✅         |
| Image Sequence | ✅         |
| Video          | ✅         |
| Audio          | ❌         |
| Text / HTML    | ❌         |
| Document       | ❌         |

### Label New Instances

<iframe title="YouTube video player" />

<Tip>
  Use the <kbd>Shift</kbd> + <kbd>A</kbd> keyboard shortcut to toggle SAM mode. Enabling SAM mode automatically activates SAM whenever the class is selected, so there's no need to click the wand icon separately.
</Tip>

1. Click the wand icon on Ontology class you want to label with.

2. Click, or click-and-drag the cursor across the part of the image you want to label.
   A popup appears.

<Tip>
  * Left-click parts of the image to include them in the label.
  * Right-click parts of the selection to exclude them from the label.
</Tip>

3. Click **Save** or press <kbd>ENTER</kbd>

### Label Existing Instances

Videos and image sequences can show a single object instance in multiple frames.

<iframe title="YouTube video player" />

1. Navigate to the frame you want to create the label.
2. Click the **Toggle auto-annotation** button or use the <kbd>SHIFT</kbd> + <kbd>A</kbd> keyboard shortcut.

<Tip>
  SAM mode remains active when switching to a different annotation class. Deactivate SAM by clicking the **Toggle auto-annotation** button, or using the <kbd>SHIFT</kbd> + <kbd>A</kbd> keyboard shortcut again.
</Tip>

3. Click, or click-and-drag the cursor across the part of the image you want to label.
   A popup appears.

<Tip>
  * Left-click parts of the image to include them in the label.
  * Right-click parts of the selection to exclude them from the label.
</Tip>

4. Click **Save** or press <kbd>ENTER</kbd>

### Label All Objects

There are two ways to label all objects of a specific Ontology class.

**Method 1**:

Click the *Sparkles* symbol in the Class.

<Tip>
  This action can be undone using <kbd>CMD / CTRL </kbd> + <kbd>Z</kbd>
</Tip>

<div>
  <img />
</div>

**Method 2**:

1. Click the *Wand* icon in the Class.

2. In the pop-up, ensure the toggle is set to **All objects prediction**.

3. Type the name of the class you want to label.

4. Click **Detect all objects**.

<div>
  <img />
</div>

5. Optionally, remove unwanted objects using the *Delete* button on an instance.

6. Click **Done**.

***

### Label One Or More Objects

1. Select the *Wand* icon in the Ontology class you want to label.
   A pop-up appears.

2. In the SAM pop-up, ensure the toggle is set to **Single-object detection**.

<div>
  <img />
</div>

3. Select the objects you want to label by either clicking a single object or clicking and dragging across the area of the frame containing multiple objects.

4. Optionally track the objects across frames.

5. Click **Save**.

***

### Panoptic Exclude Mode

When creating bitmask labels with single object detection, you can use panoptic exclude mode to automatically exclude existing bitmasks from new labels. This prevents overlapping bitmasks and ensures clean, non-overlapping annotations.

<Note>
  Panoptic exclude mode only works with bitmask annotations and is automatically applied when using SAM.
</Note>

To use panoptic exclude mode:

1. Enable **SAM mode** by clicking the wand icon or pressing <kbd>Shift</kbd> + <kbd>A</kbd>
2. Select the **Bitmask** annotation class
3. In the bitmask settings panel, set **Panoptic mode** to **Exclude**
4. Use SAM single object detection to create new bitmask labels

When you create a new bitmask with SAM, it automatically excludes any existing bitmasks in the same area, ensuring your annotations don't overlap.

***

## Tracking

Encord supports tracking objects forwards and backwards across multiple frames. This allows you to create labels for an object in one frame and automatically generate labels for the same object in subsequent frames.

<Note>
  Video tracking is computationally intensive and performance might be slower than other labeling actions.
</Note>

### Availability

The following table shows the Ontology shapes for which forwards and backwards tracking can be used.

| **Ontology shape**     | **SAM Tracking** |
| ---------------------- | ---------------- |
| Bounding box           | ✅                |
| Rotatable bounding box | ✅                |
| Polygon                | ✅                |
| Polyline               | ✅                |
| Object Primitive       | ✅                |
| Keypoint               | ✅                |
| Bitmask                | ✅                |

The following table shows the modalities that support forwards and backwards tracking.

| **Modalities**  | **SAM Tracking**   |
| --------------- | ------------------ |
| Images          | ❌                  |
| Videos          | ✅                  |
| Image Groups    | ✅  (Forwards only) |
| Image Sequences | ✅  (Forwards only) |
| DICOM           | ✅  (Forwards only) |
| Audio           | ❌                  |
| Text / HTML     | ❌                  |
| Documents       | ❌                  |

### Track While Creating Labels (Bounding Boxes, Polygons, Bitmasks)

Before you begin, set your tracking range in the [Editor Settings](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts#object-tracking). By default, object tracking is configured to run for 30 frames. This means objects are tracked forwards or backwards across 30 consecutive frames.

1. Click the *wand* icon next to the class you want to label, or press <kbd>Shift</kbd> + <kbd>A</kbd> to toggle SAM mode.

2. Click the instance you want to label. Adjust your label until the correct region is selected (if needed).

3. Specify the number of frames you want to track the instance across.

4. Click **Backwards** or **Forwards** to start the tracking algorithm.

<Note>
  You can also use keyboard shortcuts to initiate tracking:

  * Tracking forwards: <kbd>SHIFT</kbd> + <kbd>T</kbd>
  * Tracking backwards: <kbd>SHIFT</kbd> + <kbd>T</kbd> + <kbd>OPTION</kbd>
</Note>

5. Click **Save** when tracking completes to save the generated labels.

<iframe title="YouTube video player" />

### Track Existing Instances

**Method 1**:

<Note>
  The **Automated labeling** feature supports tracking forwards through data units. Specify frames after the existing frame to track.
</Note>

1. Click **Automated labeling**.

2. Expand the **Tracking and interpolation** section.

3. Select the instances you want to track.

4. Make sure the **Tracking** method is selected.

5. Set the **tracking annotation interval**. This defines how many consecutive frames an instance can be missing before the tracking algorithm stops.

6. Specify the **frame range** you want to track the selected instances across.

7. Click **Run tracking** to begin the process.

<iframe title="YouTube video player" />

**Method 2**:

Before you begin, set your default tracking range in the [Editor Settings](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts#object-tracking). By default, object tracking is configured to run for 30 frames, meaning SAM tracking tracks the object forwards or backwards across 30 consecutive frames.

1. Right-click the instance label you want to start tracking.

2. Click **Track forwards** or **Track backwards** to run tracking for 30 consecutive frames.

   <Note>
     You can also use keyboard shortcuts to initiate tracking:

     * Tracking forwards: <kbd>SHIFT</kbd> + <kbd>T</kbd>
     * Tracking backwards: <kbd>SHIFT</kbd> + <kbd>T</kbd> + <kbd>OPTION</kbd>
   </Note>

<iframe title="YouTube video player" />

**Method 3 — Configurable editor object table**:

In the configurable editor, you can initiate tracking directly from the object table without using the sidebar or right-clicking on the canvas.

<Note>
  **Track forwards** and **Track backwards** only appear in the row menu for trackable shapes on frame-based media (videos, image sequences, image groups, and DICOM). These options are hidden in view-only mode.
</Note>

1. Hover over the instance row in the object table. A **…** (more actions) button appears at the end of the row.

2. Click the **…** button to open the actions menu.

3. Click **Track forwards** or **Track backwards** to start tracking using your configured tracking range.

### Tracking Multiple Objects

To track multiple objects of any shape:

1. Click one of the objects you want to track.

2. Hold <kbd>Shift</kbd> on your keyboard and select all the other objects you want to track.

3. Right-click on one of the selected objects and click **Track forwards all** or **Track backwards all**.

<Note>
  You can also use keyboard shortcuts to initiate tracking on multiple object instances:

  * Track forwards all: <kbd>SHIFT</kbd> + <kbd>T</kbd>
  * Track backwards all: <kbd>SHIFT</kbd> + <kbd>T</kbd> + <kbd>OPTION</kbd>
</Note>

<iframe title="YouTube video player" />

***

### Settings

The *Object tracking* section of the [editor settings](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts#object-tracking) allows you to adjust the following.

**Change Tracking Range**

The range that tracking runs can be adjusted in the *Object tracking* section of the [editor settings](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts#object-tracking). The default tracking range is set to 30 frames. This range includes the frame that tracking starts on.

**Advanced Tracking**

This toggle lets you choose between a faster, simpler tracking algorithm or a slower, more advanced one with higher accuracy. The advanced algorithm is enabled by default.


# Setup and Register
Source: https://docs.encord.com/platform-documentation/Annotate/automated-labeling/setup-register-custom-agents



Custom agents let you plug your own HTTPS endpoints into Encord and trigger them in the Label Editor, or as part of your Workflow.

## Set Up Custom Agents

First you must [create and host](/agents-documentation/Custom-Agents/GCP-Cloud-Functions) the HTTPS endpoint that acts as your agent.

At a high level, your backend should:

* Accept a JSON payload from Encord describing the current project, data item, and frame.
* Use the Encord SDK or API (and any external models you choose) to perform work.
* Write results back to Encord (for example, updating labels or classifications).
* Return a successful HTTP status code so the editor knows the request completed.

Once saved, the agent appears in the **Enabled** tab of the Agents section.

### Installation

We recommend installing the Encord agents library in an isolated environment. To install `encord-agents` in your current environment, run:

<Tip>
  Installing the `vision` extras is advised for most users. These dependencies optimize performance when handling visual data formats.
</Tip>

<Warning>Encord Agents requires `python >= 3.10`. If you do not have Python 3.10, we recommend using[`pyenv`](https://github.com/pyenv/pyenv) to manage your Python versions.</Warning>

<CodeGroup>
  We recommend installing the Encord agents library in an isolated environment. To install `encord-agents` in your current environment, run:

  ```shell Visual Data theme={"dark"}
  python -m pip install "encord-agents[vision]"
  ```

  ```shell No Visual Data theme={"dark"}
  python -m pip install encord-agents
  ```
</CodeGroup>

## Register Custom Agents

<Note>Only HTTPS endpoints are supported for Custom Agents.</Note>

**To register a Custom Agent using the Agents Catalog:**

1. Go to **Agents** in the left-hand navigation.
2. In the **Agents catalog** tab, select the **Custom agent** tile.

<div>
  <img />
</div>

3. Fill in the form:
   * Give the agent a clear name and description.
   * Provide the public HTTPS endpoint that Encord should call.
   * Enter possible decisions that the agent can return (for example, "approve" or "reject"). These decisions are represented as pathways in the Workflow. If your agent does not return decisions, you can leave this field blank.
4. Save the configuration to register the Custom Agent.


# Roles and Permissions
Source: https://docs.encord.com/platform-documentation/Annotate/roles-and-permissions



## Integrations

Integrations have the following user based access controls.

<div>
  | Permission                          | Admin | User |
  | ----------------------------------- | ----- | ---- |
  | View integration                    | ✅     | ✅    |
  | Register data using the integration | ✅     | ❌    |
  | Rename integration                  | ✅     | ❌    |
  | Delete integration                  | ✅     | ❌    |
  | Add users                           | ✅     | ❌    |
</div>

## Projects

The table below illustrates the role-based access control for various Project actions available to different user types.

<Note>
  Contact [support](mailto:support@encord.com) to gain access to the Viewer role for your Projects.
</Note>

<Note>
  Viewers on Workflow projects can access the **Explore** tab in read-only mode. They can browse grid, analytics, and embeddings views and apply existing filters, but cannot create or modify collections, filter presets, or prediction sets, and cannot perform bulk actions. Viewers can still post comments and raise issues. The **Explore** tab remains inaccessible for all roles on ManualQA projects.
</Note>

| Permission                                                     | Project Admin | Team Manager            | Reviewer    | Annotator     | Annotator & Reviewer | Viewer        |
| -------------------------------------------------------------- | ------------- | ----------------------- | ----------- | ------------- | -------------------- | ------------- |
| Attach / Detach Datasets                                       | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Attach / Switch Ontology                                       | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Delete                                                         | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Invite team members                                            | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Manage team permissions                                        | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Manage admins                                                  | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Annotate & review tasks                                        | ✅             | ✅                       | Review only | Annotate only | ✅                    | ❌             |
| Confirm annotations                                            | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Control task assignments and status                            | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Exporting labels                                               | ✅             | ❌                       | ❌           | ❌             | ❌                    | ❌             |
| Assign and Release Tasks                                       | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Assign task (per-row, label queue)                             | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Release task (per-row, label queue)                            | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Change task priority (per-row, label queue)                    | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Move task to stage (per-row, label queue)                      | ✅             | ✅                       | ❌           | ❌             | ❌                    | ❌             |
| Browse and inspect labels (all workflow stages)                | ✅             | ✅                       | ✅           | ✅             | ✅                    | ✅             |
| Create and resolve comments                                    | ✅             | ✅                       | ✅           | ✅             | ✅                    | ✅             |
| Access Project Explorer (Explore tab) — Workflow projects only | ✅             | ✅ (statistics fallback) | ❌           | ❌             | ❌                    | ✅ (read-only) |

### Consensus

Certain tabs can only be accessed by specific users roles.

<div>
  | **Tab**   | Annotator | Reviewer\* | Annotator + Reviewer\* | Team Manager | Admin |
  | --------- | --------- | ---------- | ---------------------- | ------------ | ----- |
  | Summary   | ❌         | ❌          | ❌                      | ✅            | ✅     |
  | Explore   | ❌         | ❌          | ❌                      | ✅            | ✅     |
  | Queue     | ✅         | ✅          | ✅                      | ✅            | ✅     |
  | Workflow  | ❌         | ❌          | ❌                      | ✅            | ✅     |
  | Analytics | ✅         | ✅          | ✅                      | ✅            | ✅     |
  | Settings  | ❌         | ❌          | ❌                      | ✅            | ✅     |
</div>

<Note>
  When **Show peer annotations** is enabled on a Consensus annotation nodes, peer annotators (all subtasks after the first) cannot initiate their task until the first annotator completes theirs. This restriction applies to all roles (annotators, collaborators, and admins) and is not role-based. The first annotator's **Initiate** button is never affected by this restriction. Once the first annotator completes their subtask, the **Initiate** button becomes available to all peer annotators. Hovering over a disabled peer **Initiate** button displays the tooltip: *"The first annotation must be completed before peer annotations can be initiated"*.
</Note>

## Ontologies

The user who created the Ontology is granted admin privileges, which gives full control over the Ontology including adding other team members as viewers and admins.

Add and manage users in the *Team* pane of the [*Settings* tab of the Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#ontology-settings).

The following table summarizes user based access control for each role.

| **Role** | **Edit structure** | **Attach/detach from Projects** | **View tree structure** | **View JSON structure** | **Manage collaborators** | Copy | Delete |
| -------- | ------------------ | ------------------------------- | ----------------------- | ----------------------- | ------------------------ | ---- | ------ |
| Viewer   | ❌                  | ✅(if Project admin)             | ✅                       | ✅                       | ❌                        | ❌    | ❌      |
| Admin    | ✅                  | ✅(if Project admin)             | ✅                       | ✅                       | ✅                        | ✅    | ✅      |

## Workflows

## Datasets

Collaborator permissions can be set in the *Team* section of the Dataset *Settings*.

<div>
  | Permission      | Admin | Viewer |
  | --------------- | ----- | ------ |
  | View dataset    | ✅     | ✅      |
  | Add data        | ✅     | ❌      |
  | Adjust settings | ✅     | ❌      |
</div>

## Data Curation

User permissions for Folders are configured by selecting a Folder in **Files**. Click **Manage access** after selecting a Folder to add or remove users from the Folder.

<Note>Only users that are a part of your Workspace settings can be added to your Folders.</Note>

Users added to your Folders have access to all files in the Folder.

<center>
  | Permission      | Admin | Viewer |
  | --------------- | ----- | ------ |
  | View Folder     | ✅     | ✅      |
  | Add data        | ✅     | ❌      |
  | Adjust settings | ✅     | ❌      |
</center>

![Manage Index Folder Permissions](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-manage-folder-permisssions.gif)

## Project Explorer (Explore Tab)

Users with the Viewer role on Workflow projects can now access the **Explore** tab and browse the Project Explorer in read-only mode. Viewers can use the grid, analytics, and embeddings views and apply existing filters, but Encord hides all mutation affordances for Viewers.

The following actions are **not available** to Viewers in the Explorer:

* Bulk actions (priority changes, bulk classify, change class, delete labels, export CSV)
* Collection management (create, edit, delete, convert, send to annotate, bulk classify, add to dataset)
* Adding or removing items from collections in the item preview (collection tags remain visible)
* Filter preset management (create, edit, delete, save) and the `Alt+P` keyboard shortcut
* The **Manage** button for prediction sets (import/delete)

Viewers **can** post comments and raise issues in the Explorer, consistent with platform-wide permissions.

<Note>The **Explore** tab remains inaccessible for all roles on ManualQA projects. Team Managers see the **Explore** tab in the project navigation but land on the statistics fallback view — this is pre-existing behavior and is unchanged.</Note>

## Label Queue

The following actions are available in the Label Queue. Per-row task management actions in the three-dot (⋯) menu are restricted by role.

| Action          | Project Admin | Team Manager | Reviewer | Annotator | Annotator & Reviewer | Viewer |
| --------------- | ------------- | ------------ | -------- | --------- | -------------------- | ------ |
| View task       | ✅             | ✅            | ✅        | ✅         | ✅                    | ✅      |
| Activity log    | ✅             | ✅            | ✅        | ✅         | ✅                    | ✅      |
| API details     | ✅             | ✅            | ✅        | ✅         | ✅                    | ✅      |
| Assign task     | ✅             | ✅            | ❌        | ❌         | ❌                    | ❌      |
| Release task    | ✅             | ✅            | ❌        | ❌         | ❌                    | ❌      |
| Change priority | ✅             | ✅            | ❌        | ❌         | ❌                    | ❌      |
| Move to stage   | ✅             | ✅            | ❌        | ❌         | ❌                    | ❌      |

<Note>**Assign** is available for annotation and review stages only. Consensus-annotation rows are coordinator tasks assigned per subtask and do not offer the per-row Assign action.</Note>

### Bulk Actions

In list and grid views, the **Actions** button appears in the floating selection toolbar only after you select one or more tasks. In explorer view, the **Actions** button remains in the top bar regardless of selection state.

The floating selection toolbar displays items in this order: **N selected · Clear · Select all · Actions**. Hover over **Select all** to see the tip for range selection using `Shift`-click.


# Create and Register Scenes
Source: https://docs.encord.com/platform-documentation/Curate/add-files/add-pcd-data



A Scene is the Encord data unit that contains 3D sensor data. It can contain point clouds, such as LiDAR and radar point clouds, camera images, camera calibration, and vehicle or robot poses. Annotators open Scenes as tasks for 3D labeling and review.

For the supported point cloud and container formats, see [Supported data formats](/platform-documentation/General/general-supported-data#point-cloud-data).

| Goal                         | Scene shape                                                                 | Use when                                                                           |
| ---------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Label one scan               | Single point cloud stream                                                   | You have one `.pcd`, `.ply`, `.las`, `.laz`, `.e57`, or similar point cloud asset. |
| Label a sequence             | Point cloud stream with frame timestamps                                    | You have multiple point cloud frames from the same sensor.                         |
| Label multimodal sensor data | Point clouds plus image streams, camera parameters, and frames of reference | You need camera projections, synchronized views, or vehicle/sensor calibration.    |

## Register a Scene with the `SceneBuilder`

<Note>
  Use the `SceneBuilder` for Scene registration whenever possible. It validates stream references before upload and keeps you from hand-maintaining large JSON payloads.
  See [Scene SDK workflow](/sdk-documentation/index-sdk/sdk-scenes) for the full documentation on the `SceneBuilder`
</Note>

Create or load a `StorageFolder` and cloud integration ID with the Python SDK, then use the `SceneBuilder` to build and upload the Scene. For method-level details, see the [SceneBuilder reference](/sdk-documentation/sdk-references/beta.scene.builder).

```python Build and Upload a Scene expandable theme={"dark"}
from uuid import UUID

from encord.beta.scene import SceneBuilder, identity_pose, intrinsics_pinhole
from encord.storage import StorageFolder


def build_scene() -> SceneBuilder:
    scene = SceneBuilder()

    # Anchor the sensor streams to the moving platform.
    ego = scene.add_for_stream("ego")
    ego.add_pose(identity_pose(), timestamp=0)

    # Matching timestamps make the point cloud and image appear together.
    scene.add_pcd_stream("lidar", frame_of_reference=ego).add_pcd(
        uri="s3://my-bucket/scenes/scene-001/lidar/000000.pcd",
        timestamp=0,
    )

    # Inline camera parameters create a camera stream named "front/camera".
    scene.add_image_stream(
        "front",
        width=1920,
        height=1080,
        intrinsics=intrinsics_pinhole(fx=1000, fy=1000, ox=960, oy=540),
        timestamp=0,
        frame_of_reference=ego,
    ).add_image(
        uri="s3://my-bucket/scenes/scene-001/front/000000.jpg",
        timestamp=0,
    )

    return scene


def register_scene(storage_folder: StorageFolder, integration_id: str) -> UUID:
    scene = build_scene()

    # Pass the SceneBuilder itself. upload_scene validates and serializes it internally.
    return storage_folder.upload_scene(
        scene=scene,
        title="scene-001",
        integration_id=integration_id,
        client_metadata={"source": "sample"},
    )
```

After registration, add the Scene item to a Dataset and create an annotation Project as you would for other data types.


# Manual Data Registration
Source: https://docs.encord.com/platform-documentation/Curate/add-files/index-register-cloud-data



<Note>
  At least one [data integration](/platform-documentation/General/annotate-data-integrations) is required to register cloud data to Encord. Encord can integrate with the following cloud service providers:

  |                                                                                                     |                                                                                                          |                                                                                                        |
  | :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
  | [AWS S3](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration)       | [Azure blob](/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration) | [GCP storage](/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration)     |
  | [Open Telekom Cloud](/platform-documentation/General/annotate-data-integrations#open-telecom-cloud) | [Wasabi](/platform-documentation/General/annotate-data-integrations/annotate-wasabi-integration)         | [MinIO](/platform-documentation/General/annotate-data-integrations/annotate-minIO-integration)         |
  | [Oracle](/platform-documentation/General/annotate-data-integrations/annotate-oracle-integration)    | [Cloudflare](/platform-documentation/General/annotate-data-integrations/annotate-cloudflare-integration) | [CoreWeave](/platform-documentation/General/annotate-data-integrations/annotate-coreweave-integration) |
</Note>

Any files you upload to Encord must be stored in folders. [Click here](/platform-documentation/Curate/index-files#create-a-folder) to learn how to create a folder to store your files.

***

## Register Cloud Data

### 1. Create a JSON or CSV File for Registration

Before registering your cloud data to Encord you must first create a JSON or CSV file specifying the files you want to register.

<Tip><b>BEST PRACTICE:</b> If you want to use Curation or Label Validation with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

#### JSON Format

<Tip>
  We provide [helpful scripts and examples](#helpful-scripts-and-examples) that automatically generate JSON and CSV files for all the files in a folder or bucket within your cloud storage. This makes importing large datasets easier and more efficient.
</Tip>

The JSON file format is a JSON object with top-level keys specifying the type of data and object URLs of the files you want to upload to Encord. You can add one data type at a time, or combine multiple data types in one JSON.

The supported top-level keys are: `videos`, `audio`, `time_series`, `image_groups`, `images`, `dicom_series`, `nifti`, `scenes`, and `data_groups`. The details for each data format are given in the sections below.

<Tip>
  See our tips for increasing the speed of file registration
  [here](/platform-documentation/Curate/add-files/index-register-cloud-data#how-to-increase-file-upload-speed).
</Tip>

<Tip>
  Add the `"skip_duplicate_urls": true` flag at the top level to make the
  uploads idempotent. Skipping URLs can help speed up large upload operations.
  Since previously processed assets do not have to be uploaded again, you can
  simply retry the failed operation without editing the upload specification
  file. The flag's default value is`false`.
</Tip>

<Info>
  Encord enforces the following upload limits for each JSON file used for file registration:

  * Up to 1 million URLs
  * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  * URLs can be up to 16 KB in size

  Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
</Info>

<AccordionGroup>
  <Accordion title="Videos">
    #### Videos

    Each object in the videos array is a JSON object with the key `objectUrl` specifying the full URL of where to find the video resource. The `title` field is optional. If omitted, the video file path and name are used as the default title. For example, if the file is located at `https://encord-solutions-bucket.s3.eu-west-2.amazonaws.com/path/to/my/bucket/video23.mp4`, the title defaults to `/path/to/my/bucket/video23.mp4`.

    <Note>
      [videoMetadata](#video-metadata) must be specified when a [Strict client-only
      access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access)
      integration is used. In all other cases, `videoMetadata` is optional, but
      including it significantly reduces import times.
    </Note>

    | Key or Flag      | Required? | Default value           |
    | ---------------- | --------- | ----------------------- |
    | "objectUrl"      | Yes       |                         |
    | "title"          | No        | the file's path + title |
    | "videoMetadata"  | No        |                         |
    | "clientMetadata" | No        |                         |
    | "createVideo"    | No        | false                   |

    <Note>
      Keys / Flags that are not required can be omitted from the JSON file entirely.
    </Note>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-custom-video-title.mp4",
            "videoMetadata": {
              "fps": 23.98,
              "duration": 29.09,
              "width": 1280,
              "height": 720,
              "file_size": 5468354,
              "mime_type": "video/mp4"
            },
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
          },
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
            "title": "my-custom-video-title.mp4",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_1.mp4"
          },
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_2.mp4",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>

    #### Video Metadata

    The JSON format allows you to specify `videoMetadata` for video files. `videoMetadata` is essential information used by the Label Editor and is crucial for aligning annotations to the correct frame.

    <Info>
      When the `videoMetadata` flag is present in the JSON file, we directly use the
      supplied metadata without performing any additional validation, and do not
      store the file on our servers. To guarantee accurate labels, it is crucial
      that the metadata you provide is accurate.
    </Info>

    <Note>
      `videoMetadata` must be specified when a [Strict client-only
      access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access)
      integration is used. In all other cases, `videoMetadata` is optional.
    </Note>

    ```json theme={"dark"}
    {
      "videos": [
        {
          "objectUrl": "video_file.mp4",
          "videoMetadata": {
            "fps": 23.98,
            "duration": 29.09,
            "width": 1280,
            "height": 720,
            "file_size": 5468354,
            "mime_type": "video/mp4"
          }
        }
      ]
    }
    ```

    * fps: Frames per second.
    * duration: Duration of the video (in seconds).
    * width / height: Dimensions of the video (in pixels).
    * file\_size: The size of the file (in bytes).
    * mime\_type: Specifies the file type extension according to the MIME standard.

    When videos are supplied with video metadata, Encord assumes the metadata to be correct and our servers will neither download nor pre-process your data. This may be a particularly useful feature for customers with strict data compliance concerns.

    One way to find the necessary metadata is shown below. Run the following commands in your terminal.

    * `ffmpeg -i 'video_title.mp4'` to retrieve fps, duration, width, and height - as highlighted below.

    <div>
      <img />
    </div>

    * `ls -l 'video_title.mp4'` to retrieve the file size - as highlighted below.

    <div>
      <img />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Audio files">
    #### Audio Files

    Each object in the audio file array is a JSON object with the key `objectUrl` specifying the full URL of where to find the audio resource. The `title` field is optional. If omitted, the audio file path and name are used as the default title. For example, if the file is located at `https://encord-solutions-bucket.s3.eu-west-2.amazonaws.com/path/to/my/bucket/song23.mp3`, the title defaults to `/path/to/my/bucket/song23.mp3`.

    <Info>
      [Audio metadata](#audio-metadata) is distinct from client metadata.
      `clientMetadata` allows you to add metadata that can be used for filtering
      your data in Index. You can use `text` to import transcripts for your audio
      file.
    </Info>

    <Note>
      [audioMetadata](#audio-metadata) must be specified when a [Strict client-only
      access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access)
      integration is used. In all other cases, `audioMetadata` is optional, but
      including it significantly reduces import times.
    </Note>

    | Key or Flag      | Required? | Default value           |
    | ---------------- | --------- | ----------------------- |
    | "objectUrl"      | Yes       |                         |
    | "title"          | No        | The file's path + title |
    | "clientMetadata" | No        |                         |
    | "audioMetadata"  | No        |                         |

    <Note>
      Keys / Flags that are not required can be omitted from the JSON file entirely.
    </Note>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "audio": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-custom-audio-file-title.mp3",
            "audioMetadata": {
              "duration": 23.98,
              "file_size": 2900000,
              "mime_type": "audio/mp3",
              "sample_rate": 44100,
              "bit_depth": 24,
              "codec": "mp3",
              "num_channels": 2
            },
            "clientMetadata": { "optional_key_1": "optional_metadata_value_1" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "audio": [
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
          },
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
            "title": "my-custom-audio-file-title.mp3",
            "clientMetadata": { "optional_key_1": "optional_metadata_value_1" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Music/2022/audio_1.mp3"
          },
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Music/2022/audio_2.mp3",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>

    #### Audio Metadata

    The JSON format allows you to specify `audioMetadata` for audio files. This is optional information.

    <Info>
      When the `audioMetadata` flag is present in the JSON file, we directly use the
      supplied metadata without performing any additional validation, and do not
      store the file on our servers. It is crucial that the metadata you provide is
      accurate.
    </Info>

    ```json theme={"dark"}
    {
      "audio": [
        {
          "objectUrl": "audio_file.mp3",
          "audioMetadata": {
            "duration": 23.98,
            "file_size": 2900000,
            "mime_type": "audio/mp3",
            "sample_rate": 44100,
            "bit_depth": 24,
            "codec": "mp3",
            "num_channels": 2
          }
        }
      ]
    }
    ```

    * duration\_seconds: float - Audio duration in seconds.
    * file\_size: int - Size of the audio file in bytes.
    * mime\_type: str - MIME type of the audio file (for example: `audio/mpeg` or `audio/wav`).
    * sample\_rate: int - Sample rate (int) in Hz.
    * bit\_depth: int - Size of each sample (int) in bits.
    * codec: str - Codec (for example: mp3, pcm).
    * num\_channels: int - Number of channels.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Time series">
    #### Time Series

    <Warning>
      Time series is in Beta. Contact your Encord support representative to enable the feature for your Organization.
    </Warning>

    Each object in the time series array is a JSON object with the key `objectUrl` specifying the full URL of where to find the CSV file. The `title` field is optional. If omitted, the CSV file path and name are used as the default title.

    | Key or Flag      | Required? | Default value           |
    | ---------------- | --------- | ----------------------- |
    | "objectUrl"      | Yes       |                         |
    | "title"          | No        | The file's path + title |
    | "clientMetadata" | No        |                         |

    <Note>
      Time series currently supports CSV files with a MIME type of `text/csv` or `application/csv`. The Label Editor parses the timestamp and channel columns when the file is opened.
    </Note>

    ```json Standard integration theme={"dark"}
    {
      "time_series": [
        {
          "objectUrl": "<object url_1>"
        },
        {
          "objectUrl": "<object url_2>",
          "title": "my-custom-time-series-title.csv",
          "clientMetadata": { "optional": "metadata" }
        }
      ]
    }
    ```

    See [Time Series](/platform-documentation/Annotate/annotate-label-editor/annotate-time-series) for CSV structure assumptions and labeling guidance.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="PDFs">
    #### PDFs

    Each object in the PDF array is a JSON object with the key `objectUrl` specifying the full URL of where to find the PDF. The `title` field is optional. If omitted, the PDF path and name are used as the default title. For example, if the file is located at `https://encord-solutions-bucket.s3.eu-west-2.amazonaws.com/path/to/my/bucket/my-document.pdf`, the title defaults to `/path/to/my/bucket/my-document.pdf`.

    <Info>
      [PDF metadata](#pdf-metadata) is distinct from client metadata.
      `clientMetadata` allows you to add metadata that can be used for filtering
      your data in Index.
    </Info>

    <Note>
      [PDF Metadata](#pdf-metadata) must be specified when a [Strict client-only
      access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access)
      integration is used. In all other cases, `pdfMetadata` is optional, but
      including it significantly reduces import times.
    </Note>

    | Key or Flag      | Required? | Default value           |
    | ---------------- | --------- | ----------------------- |
    | "objectUrl"      | Yes       |                         |
    | "title"          | No        | The file's path + title |
    | "clientMetadata" | No        |                         |
    | "pdfMetadata"    | No        |                         |

    <Note>
      Keys / Flags that are not required can be omitted from the JSON file entirely.
    </Note>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "<object url_1>",
            "pdfMetadata": {
              "fileSize": 300,
              "numPages": 5
            }
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-document-02.pdf",
            "clientMetadata": { "optional_key_1": "optional_metadata_value_1" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>",
            "pdfMetadata": {
              "fileSize": 300,
              "numPages": 5
            }
          },
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
            "title": "my-document.pdf",
            "clientMetadata": { "optional_key_1": "optional_metadata_value_1" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Docs/2022/file_1.pdf",
            "pdfMetadata": {
              "fileSize": 300,
              "numPages": 5
            }
          },
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Docs/2022/file_2.pdf",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>

    #### PDF Metadata

    The JSON format allows you to specify `pdfMetadata` for documents. This is optional information.

    <Info>
      When the `pdfMetadata` flag is present in the JSON file, we directly use the
      supplied metadata without performing any additional validation, and do not
      store the file on our servers. It is crucial that the metadata you provide is
      accurate.
    </Info>

    ```json theme={"dark"}
    {
      "pdfs": [
        {
          "objectUrl": "https://storage.cloud.google.com/encord-onboarding-clinton/text/singapore-penal-code-1871.pdf",
          "pdfMetadata": {
            "fileSize": 300,
            "numPages": 5
          }
        }
      ]
    }
    ```

    * file\_size: int - Size of the pdf file in bytes.
    * num\_pages: int - The number of pages in the PDF document.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Text Files">
    #### Text Files

    Each object in the text file array is a JSON object with the key `objectUrl` specifying the full URL of where to find the text file. The `title` field is optional. If omitted, the text file path and name are used as the default title. For example, if the file is located at `https://encord-solutions-bucket.s3.eu-west-2.amazonaws.com/path/to/my/bucket/my-file.html`, the title defaults to `/path/to/my/bucket/my-file.html`.

    <Note>Text files include .txt, .html, .md, .xml, and more.</Note>

    <Info>
      [Text metadata](#text-metadata) is distinct from client metadata.
      `clientMetadata` allows you to add metadata that can be used for filtering
      your data in Index.
    </Info>

    <Note>
      [textMetadata](#text-metadata) must be specified when a [Strict client-only
      access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access)
      integration is used. In all other cases, `textMetadata` is optional, but
      including it significantly reduces import times.
    </Note>

    | Key or Flag      | Required? | Default value           |
    | ---------------- | --------- | ----------------------- |
    | "objectUrl"      | Yes       |                         |
    | "title"          | No        | The file's path + title |
    | "clientMetadata" | No        |                         |
    | "textMetadata"   | No        |                         |

    <Note>
      Keys / Flags that are not required can be omitted from the JSON file entirely.
    </Note>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "<object url_1>",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-file.html",
            "clientMetadata": { "optional_key_1": "optional_metadata_value_1" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
            "title": "my-file.html",
            "clientMetadata": { "optional_key_1": "optional_metadata_value_1" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Text/2022/essay_1.txt",
            "textMetadata": {
              "fileSize": 240,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Text/2022/essay_2.txt",
            "textMetadata": {
              "fileSize": 240,
              "mime_type": "text/plain"
            },
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>

    #### Text Metadata

    The JSON format allows you to specify `textMetadata` for documents. This is optional information.

    <Info>
      When the `textMetadata` flag is present in the JSON file, we directly use the
      supplied metadata without performing any additional validation, and do not
      store the file on our servers. It is crucial that the metadata you provide is
      accurate.
    </Info>

    ```json theme={"dark"}
    {
      "text": [
        {
          "objectUrl": "<object url_1>",
          "textMetadata": {
            "fileSize": 200,
            "mime_type": "application/xml"
          }
        }
      ]
    }
    ```

    * file\_size: int - Size of the text file in bytes.
    * mime\_type: str - MIME type of the text file (for example: `application/xml` or `text/plain`).
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    #### [Single Images](#single-images)

    The JSON structure for [single images](#single-images) parallels that of videos. The `title` field is optional. If omitted, the image file path and name are used as the default title. For example, if the file is located at `https://encord-solutions-bucket.s3.eu-west-2.amazonaws.com/path/to/my/bucket/image23.jpg`, the title defaults to `/path/to/my/bucket/image23.jpg`.

    | Key or Flag       | Required? | Default value           |
    | ----------------- | --------- | ----------------------- |
    | "objectUrl"       | Yes       |                         |
    | "title"           | No        | The file's path + title |
    | "imageMetadata"\* | No        |                         |
    | "clientMetadata"  | No        |                         |
    | "createVideo"     | No        | false                   |

    <Note>
      [imageMetadata](#image-metadata) must be specified when a [Strict client-only
      access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access)
      integration is used. In all other cases, `imageMetadata` is optional, but
      including it significantly reduces import times.
    </Note>

    <Note>
      Keys / Flags that are not required can be omitted from the JSON file entirely.
    </Note>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "<object url>"
          },
          {
            "objectUrl": "<object url>",
            "title": "my-custom-image-title.jpeg",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            },
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
          },
          {
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
            "title": "my-custom-image-file-title.png",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            },
            "clientMetadata": { "optional_key_1": "optional_metadata_value_1" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_1.jpg"
          },
          {
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_2.jpg",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>

    #### Image Metadata

    The JSON format allows you to specify `imageMetadata` for image files. `imageMetadata` contains essential information used by the Label Editor and is crucial for aligning annotations to the correct image properties.

    <Warning>
      When the `imageMetadata` flag is present in the JSON file, we directly use the
      supplied metadata without performing any additional validation and do not
      store the file on our servers. To guarantee accurate labels, it is crucial
      that the metadata you provide is accurate.
    </Warning>

    <Note>
      `imageMetadata` must be specified when a [Strict client-only
      access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access)
      integration is used. In all other cases, `imageMetadata` is optional.
    </Note>

    ```json theme={"dark"}
    {
      "images": [
        {
          "objectUrl": "s3://my_image.jpg",
          "imageMetadata": {
            "mimeType": "image/jpg",
            "fileSize": 124,
            "width": 640,
            "height": 480
          }
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### [Image groups](#image-groups)

    * [Image groups](#image-groups) are collections of images that are processed as one annotation task.
    * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
    * Image groups do not require 'write' permissions to your cloud storage.
    * [Custom client metadata](/platform-documentation/Curate/add-files/index-register-cloud-data#custom-metadata) is defined per image group, not per image. See our documentation [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata#add-custom-metadata-to-images-in-an-image-group) to learn how to add `clientMetadata` to images in an image group.

    | Key or Flag      | Required? | Default value | Note                                                              |
    | ---------------- | --------- | ------------- | ----------------------------------------------------------------- |
    | "objectUrl\_"    | Yes       |               |  is the number the file occupies in the sequence, starting from 0 |
    | "title"          | No        |               |                                                                   |
    | "clientMetadata" | No        |               |                                                                   |
    | "createVideo"    | No        | `false`       |                                                                   |

    <Note>
      The position of each image within the sequence needs to be specified in the
      key - e.g. `objectUrl_{position_number}` as seen in the example below.
    </Note>

    <Note>
      Keys / Flags that are not required can be omitted from the JSON file entirely.
    </Note>

    <Warning>
      Custom metadata (`clientMetadata`) can be added to individual frames in an
      image group. However, the frames must first be imported into Index, after
      which you can [create an image group from the frames using the
      SDK](/sdk-documentation/index-sdk/sdk-upload-data#create-an-image-group-from-existing-images).
    </Warning>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "image_groups": [
          {
            "title": "<title 1>",
            "createVideo": false,
            "objectUrl_0": "<object url>",
            "objectUrl_1": "<object url>",
            "objectUrl_2": "<object url>"
          },
          {
            "title": "<title 2>",
            "createVideo": false,
            "objectUrl_0": "<object url>",
            "objectUrl_1": "<object url>",
            "objectUrl_2": "<object url>",
            "clientMetadata": { "optional": "imageGroupMetadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "image_groups": [
          {
            "title": "<title 1>",
            "createVideo": false,
            "objectUrl_0": "Multi-Region-Access-Point-ARN + <object name_0>",
            "objectUrl_1": "Multi-Region-Access-Point-ARN + <object name_1>"
          },
          {
            "title": "<title 2>",
            "createVideo": false,
            "objectUrl_0": "Multi-Region-Access-Point-ARN + <object name_0>",
            "objectUrl_1": "Multi-Region-Access-Point-ARN + <object name_1>",
            "objectUrl_2": "Multi-Region-Access-Point-ARN + <object name_2>",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "image_groups": [
          {
            "title": "Insects",
            "createVideo": false,
            "objectUrl_0": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_0.jpg",
            "objectUrl_1": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_1.jpg"
          },
          {
            "title": "Plants",
            "createVideo": false,
            "objectUrl_0": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_2.jpg",
            "objectUrl_1": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_3.jpg",
            "objectUrl_2": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_4.jpg",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### [Image Sequences](#image-sequences)

    * [Image sequences](#image-sequences) are collections of images that are processed as one annotation task and represented as a video.
    * Images within image sequences may be altered as images of varying sizes are resolutions are made to match that of the first image in the sequence.
    * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
    * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
    * Custom client metadata is defined per image sequence, not per image.

    <Tip>
      The only difference between adding image groups and image sequences via a JSON
      is that image sequences require the `createVideo` flag to be set to `true`.
      Both use the key `image_groups`.
    </Tip>

    | Key or Flag      | Required? | Default value |
    | ---------------- | --------- | ------------- |
    | "objectUrl"      | Yes       |               |
    | "title"          | No        |               |
    | "clientMetadata" | No        |               |
    | "createVideo"    | no        | `false`       |

    <Note>
      The position of each image within the sequence needs to be specified in the
      key - e.g `objectUrl_{position_number}`. See the example below.
    </Note>

    <Note>
      Keys / Flags that are not required can be omitted from the JSON file entirely.
    </Note>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "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" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "image_groups": [
          {
            "title": "<title 1>",
            "createVideo": true,
            "objectUrl_0": "Multi-Region-Access-Point-ARN + <object name_0>"
          },
          {
            "title": "<title 2>",
            "createVideo": true,
            "objectUrl_0": "Multi-Region-Access-Point-ARN + <object name_0>",
            "objectUrl_1": "Multi-Region-Access-Point-ARN + <object name_1>",
            "objectUrl_2": "Multi-Region-Access-Point-ARN + <object name_2>",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "image_groups": [
          {
            "title": "Insects",
            "createVideo": true,
            "objectUrl_0": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_0.jpg"
          },
          {
            "title": "Plants",
            "createVideo": true,
            "objectUrl_0": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_2.jpg",
            "objectUrl_1": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_3.jpg",
            "objectUrl_2": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Images/2022/image_4.jpg",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    #### [DICOM](#dicom)

    * Each `dicom_series` element can contain one or more DICOM series.
    * Each series requires a title and at least one object URL, as shown in the following example.

    | Key or Flag                     | Required? | Default value | Note                                                                                 |
    | :------------------------------ | :-------- | :------------ | :----------------------------------------------------------------------------------- |
    | `"objectUrl_{position_number}"` | Yes       |               | `{position_number}` is the number the file occupies in the sequence, starting from 0 |
    | `"title"`                       | Yes       |               |                                                                                      |
    | `"clientMetadata"`              | No        |               |                                                                                      |

    <Note>
      Keys / Flags that are required, such as `clientMetadata`, can be omitted from
      the JSON file entirely. `clientMetadata` is distinct from patient metadata,
      which is included in the `.dcm` file and does not have to be specific during
      the upload to Encord.
    </Note>

    The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

    * The first series contains only a single object URL, as it is composed of a single file.
    * The second series contains 3 object URLs, as it is composed of three separate files.
    * The third series contains 2 object URLs, as it is composed of two separate files.

    <Info>
      For each DICOM upload, an additional `DicomSeries` file is created. This file
      represents the series file-set. Only `DicomSeries` are displayed in the Encord
      application.
    </Info>

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "dicom_series": [
          {
            "title": "<series-1>",
            "objectUrl_0": "https://my-bucket/.../study1-series1-file.dcm"
          },
          {
            "title": "<series-2>",
            "objectUrl_0": "https://my-bucket/.../study1-series2-file1.dcm",
            "objectUrl_1": "https://my-bucket/.../study1-series2-file2.dcm",
            "objectUrl_2": "https://my-bucket/.../study1-series2-file3.dcm"
          },
          {
            "title": "<series-3>",
            "objectUrl_0": "https://my-bucket/.../study1-series3-file1.dcm",
            "objectUrl_1": "https://my-bucket/.../study1-series3-file2.dcm"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "dicom_series": [
          {
            "title": "<series-1>",
            "objectUrl_0": "Multi-Region-Access-Point-ARN + <object name_0>"
          },
          {
            "title": "<series-2>",
            "objectUrl_0": "Multi-Region-Access-Point-ARN + <object name_0>",
            "objectUrl_1": "Multi-Region-Access-Point-ARN + <object name_1>",
            "objectUrl_2": "Multi-Region-Access-Point-ARN + <object name_2>"
          },
          {
            "title": "<series-3>",
            "objectUrl_0": "Multi-Region-Access-Point-ARN + <object name_0>",
            "objectUrl_1": "Multi-Region-Access-Point-ARN + <object name_1>"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "dicom_series": [
          {
            "title": "CT Scans",
            "objectUrl_0": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/DICOM/2022/image_0.jpg"
          },
          {
            "title": "MRI",
            "objectUrl_0": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/DICOM/2022/image_2.jpg",
            "objectUrl_1": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/DICOM/2022/image_3.jpg",
            "objectUrl_2": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/DICOM/2022/image_4.jpg",
            "clientMetadata": { "optional": "metadata" }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="NIfTI">
    #### [NIfTI](#nifti)

    Each series requires a title and at least one object URL.

    | Key or Flag      | Required? | Default value    |
    | ---------------- | --------- | ---------------- |
    | "objectUrl"      | Yes       |                  |
    | "title"          | No        | The file's title |
    | "clientMetadata" | No        |                  |

    The following is an example JSON file for uploading two NIfTI files to Encord.

    <CodeGroup>
      ```json Standard integration theme={"dark"}
      {
        "nifti": [
          {
            "title": "<file-1>",
            "objectUrl": "https://my-bucket/.../nifti-file1.nii"
          },
          {
            "title": "<file-2>",
            "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Multi-region access point (AWS) theme={"dark"}
      {
        "nifti": [
          {
            "title": "<file-1>",
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
          },
          {
            "title": "<file-2>",
            "objectUrl": "Multi-Region-Access-Point-ARN + <object name_0>"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json MRAP Example theme={"dark"}
      {
        "nifti": [
          {
            "title": "img1",
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/NIFTI/2022/image_1.img
      "
          },
          {
            "title": "img2",
            "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/NIFTI/2022/image_2.img
      "
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Data groups">
    #### [Data Groups](#data-groups)

    * Data groups let you combine multiple data items from the cloud upload into a single annotation task with a multi-pane layout.
    * The contents of the group are created by specifying `titleRef` (matching the `title` field of another item) or `urlRef` (matching the `objectUrl` of another item). The referenced items must be defined in the same JSON file.

    There are three layout types:

    | Layout type      | Description                                                                                                           |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
    | `"default-grid"` | Arranges items in an auto-generated grid. `layoutContents` is an array of refs.                                       |
    | `"default-list"` | Arranges items in a carousel. `layoutContents` is an array of refs.                                                   |
    | `"custom"`       | Uses a custom split-pane layout. `layoutContents` is an object with named keys, and a `layout` tree must be provided. |

    <CodeGroup>
      ```json default-grid theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://my-bucket/image1.png",
            "title": "image-1"
          },
          {
            "objectUrl": "https://my-bucket/image2.png",
            "title": "image-2"
          }
        ],
        "data_groups": [
          {
            "name": "my-grid-group",
            "layoutType": "default-grid",
            "layoutContents": [{ "titleRef": "image-1" }, { "titleRef": "image-2" }]
          }
        ]
      }
      ```

      ```json default-list theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://my-bucket/image1.png",
            "title": "image-1"
          },
          {
            "objectUrl": "https://my-bucket/image2.png",
            "title": "image-2"
          }
        ],
        "data_groups": [
          {
            "name": "my-list-group",
            "layoutType": "default-list",
            "layoutContents": [
              { "urlRef": "https://my-bucket/image1.png" },
              { "urlRef": "https://my-bucket/image2.png" }
            ]
          }
        ]
      }
      ```

      ```json custom layout theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "https://my-bucket/instructions.html",
            "title": "instructions"
          }
        ],
        "images": [
          {
            "objectUrl": "https://my-bucket/photo.png",
            "title": "photo"
          }
        ],
        "data_groups": [
          {
            "name": "custom-layout-group",
            "layoutType": "custom",
            "layoutContents": {
              "left": { "titleRef": "instructions" },
              "right": { "titleRef": "photo" }
            },
            "layout": {
              "direction": "column",
              "splitPercentage": 30,
              "first": { "type": "data_unit", "key": "left" },
              "second": { "type": "data_unit", "key": "right" }
            },
            "clientMetadata": { "batch": "review-set-1" }
          }
        ]
      }
      ```
    </CodeGroup>

    #### Custom Layout

    The `layout` field is a custom layout defined with a recursive binary split tree. Each node is one of:

    * **`data_unit`**: A single pane displaying one data item. Requires a `key` matching a key in `layoutContents`.
    * **`data_unit_list`**: A carousel pane displaying multiple data items. Requires `keys` (array of keys from `layoutContents`). Optional fields: `carouselPosition` (`"left"`, `"right"`, `"top"`, `"bottom"`; default `"left"`) and `carouselSize` (10-70; default 20).
    * **Grid node**: Splits the area into two children. Requires `direction` (`"row"` or `"column"`), `first`, `second`, and `splitPercentage` (5-95).

    #### Settings

    The optional `settings` object supports:

    | Key                   | Type   | Default | Description                                                                                                                      |
    | --------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
    | `fixedLayout`         | bool   | `false` | Prevents users from changing the layout in the Label Editor.                                                                     |
    | `hasMultilayerLabels` | bool   | `false` | When `true`, labels are placed on all elements in the data group.                                                                |
    | `tileSettings`        | object |         | Per-tile settings keyed by `layoutContents` key. Each tile can have a `title` (string) and `isReadOnly` (bool, default `false`). |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Scenes">
    #### [Scenes](#scenes)

    Scenes are used for point cloud (PCD/LiDAR) data and can combine multiple sensor streams (cameras, LiDAR) into a single annotation task.

    For full details on the scene JSON format, supported streams, frames of reference, and examples, see the [Add Point Cloud Data](/platform-documentation/Curate/add-files/add-pcd-data) documentation.
  </Accordion>
</AccordionGroup>

#### Use a Multi-Region Access Point

When using a Multi-Region Access Point for your AWS S3 buckets the JSON file has to be slightly different from the examples provided. Instead of an object's URL, objects are specified using the ARN of the Multi-Region Access Point followed by the object name. The example below shows how video files from a Multi-Region Access Point would be specified.

```json theme={"dark"}
{
  "videos": [
    {
      "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
    },
    {
      "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
      "title": "my-custom-video-title.mp4"
    }
  ],
  "skip_duplicate_urls": true
}
```

```json MRAP Example theme={"dark"}
{
  "videos": [
    {
      "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_1.mp4"
    },
    {
      "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_2.mp4",
      "title": "many-cute-cats.mp4"
    }
  ],
  "skip_duplicate_urls": true
}
```

#### CSV Format

In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file.

Details for each data format are given in the sections below.

<Info>Encord supports up to 10,000 entries for upload in the CSV file.</Info>

<Warning>
  * Object URLs can't contain whitespace.
  * For backwards compatibility reasons, a single column CSV is supported. A file with the single `ObjectUrl` column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: "Expected a video, got a file of type XXX".
</Warning>

<AccordionGroup>
  <Accordion title="Videos">
    #### Videos

    A CSV file containing videos should contain two columns with the following mandatory column headings:\
    'ObjectURL' and 'Video title'. All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the video resource.

    * The 'Video title' column containing the `video_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Video title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.mp4 | Video 1     |
    | path/to/storage-location/frame2.mp4 | Video 2     |
    | path/to/storage-location/frame3.mp4 |             |
    | path/to/storage-location/frame4.mp4 | Video 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    A CSV file containing single images should contain two columns with the following mandatory headings:\
    'ObjectURL' and 'Image title'.  All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the image resource.

    * The 'Image title' column containing the `image_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Image title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.jpg | Image 1     |
    | path/to/storage-location/frame2.jpg | Image 2     |
    | path/to/storage-location/frame3.jpg |             |
    | path/to/storage-location/frame4.jpg | Image 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### Image groups

    A CSV file containing image groups should contain three columns with the following mandatory headings:\
    'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image group a file will be assigned to.

    In the example below the first two URLs are grouped together into 'Group 1', while the following two files are grouped together into 'Group 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Group 1           | false        |
    | path/to/storage-location/frame2.jpg | Group 1           | false        |
    | path/to/storage-location/frame3.jpg | Group 2           | false        |
    | path/to/storage-location/frame4.jpg | Group 2           | false        |

    <Note>Image groups do not require 'write' permissions.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### Image sequences

    A CSV file containing image sequences should contain three columns with the following mandatory headings: 'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.

    * The 'Create video' column. This can be left blank, as the default value is 'true'.

    In the example below the first two URLs are grouped together into 'Sequence 1', while the second two files are grouped together into 'Sequence 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |

    <Tip>Image groups and image sequences are only distinguished by the presence of the 'Create video' column.</Tip>

    <Note>Image sequences require 'write' permissions against your storage bucket to save the compressed video.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    A CSV file containing DICOM files should contain two columns with the following mandatory headings: 'ObjectURL' and 'Dicom title'. Both headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Series title' column containing the `dicom_title`. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.

    In the example below the first two files are grouped into 'dicom series 1', the next two files are grouped into 'dicom series 2', while the final file will remain separated as 'dicom series 3'.

    | ObjectUrl                           | Series title   |
    | ----------------------------------- | -------------- |
    | path/to/storage-location/frame1.dcm | dicom series 1 |
    | path/to/storage-location/frame2.dcm | dicom series 1 |
    | path/to/storage-location/frame3.dcm | dicom series 2 |
    | path/to/storage-location/frame4.dcm | dicom series 2 |
    | path/to/storage-location/frame5.dcm | dicom series 3 |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    #### Multiple file types

    You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.

    <Warning>Since the 'Create video' column defaults to `true` all files that **are not** image sequences must contain the value `false`</Warning>

    The example below shows a CSV file for the following:

    * Two image sequences composed of 2 files each.
    * One image group composed of 2 files.
    * One single image.
    * One video.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame5.jpg | Group 1           | false        |
    | path/to/storage-location/frame6.jpg | Group 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | path/to/storage-location/frame1.jpg | Image 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | full/storage/path/video.mp4         | Video 1           | false        |
  </Accordion>
</AccordionGroup>

***

### 2. Register Your Cloud Data

<Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

1. Navigate to **Data** > **Files & Folders** in the Encord platform.
2. Click into a Folder.
3. Click **+ Upload files**.
   A dialog appears.

<div>
  <img />
</div>

4. Click **Import from cloud data**.

<div>
  <img />
</div>

<Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.

<Tip> You can also register your data directly in the *Datasets* screen. [Click here](/platform-documentation/Annotate/annotate-datasets/annotate-datasets) for instructions.</Tip>

***

## Custom Metadata

Custom metadata, also known as client metadata, is supplementary information you can add to all data imported into Encord. It is provided in the form of a Python dictionary, as shown in examples. Client metadata serves several key functions:

* Filtering and sorting in Index and Active.
* Creating [custom Label Editor layouts](/platform-documentation/Annotate/annotate-label-editor#editor-layout) based on metadata.

You can optionally add some custom metadata per data item in the `clientMetadata` field (examples show how this is done) of your JSON file.For example, for a video of a construction site, custom metadata could include fields like `"site_location": "Algiers"`, `"project_phase": "foundation"`, or `"weather_conditions": "sunny"`. This enables more precise tracking and management of your data.

Before importing any files with custom metadata to Encord, we recommend that you import a [metadata schema](#metadata-schema). Encord uses metadata schemas to validate custom metadata uploaded to Encord and to instruct Index and Active how to display your metadata.

<Info>
  There is no limit on the number of custom metadata fields on a data unit. However, we enforce a 10MB limit on the custom metadata for each data item. Internally, we store custom metadata as a PostgreSQL `jsonb` type. Read the [relevant PostgreSQL documentation](https://www.postgresql.org/docs/9.5/datatype-json.html) about the `jsonb` type and its behaviors. For example, `jsonb` type does not preserve key order or duplicate keys.
</Info>

<Tip>To handle your custom metadata schema across multiple teams within the same workspace, we recommend using namespacing for metadata keys in the schema. This ensures that different teams can define and manage their own metadata schema without conflicts. For example, team A could use `video.description`, while team B could use `audio.description`. Another example could be `TeamName.MetadataKey`. This approach maintains clarity and avoids key collisions across departments.</Tip>

### Metadata Schema

<Note>
  Metadata schemas, including custom embeddings, can only be imported through the Encord SDK.
</Note>

Based on your Data Discoverability Strategy, you need to create a metadata schema. The schema provides a method of organization for your custom metadata. Encord supports:

* Scalars: Methods for filtering.
* Enums: Methods with options for filtering.
* Embeddings: Method for embedding plot visualization, similarity search, and natural language search.

<Tip>Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and the following blank spaces ( ), hyphens (-), underscores (\_), and periods (.).</Tip>

### Metadata schema table

<Tip>Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and blank spaces ( ), hyphens (-), underscores (\_), and periods (.). Metadata schema keys are case sensitive.</Tip>

Use `add_scalar` to add a scalar key to your metadata schema.

| Scalar Key | Description                                                                                                                                                                                | Display Benefits                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| boolean    | Binary data type with values "true" or "false".                                                                                                                                            | Filtering by binary values                        |
| datetime   | ISO 8601 formatted date and time.                                                                                                                                                          | Filtering by time and date                        |
| number     | Numeric data type supporting float values.                                                                                                                                                 | Filtering by numeric values                       |
| uuid       | UUIDv4 formatted unique identifier for a data unit.                                                                                                                                        | Filtering by customer specified unique identifier |
| varchar    | Textual data type. Formally `string`. `string` can be used as an alias for `varchar`, but we STRONGLY RECOMMEND that you use `varchar`.                                                    | Filtering by string.                              |
| text       | Text data with unlimited length (example: transcripts for audio). Formally `long_string`. `long_string` can be used as an alias for `text`, but we STRONGLY RECOMMEND that you use `text`. | Storing and filtering large amounts of text.      |

Use `add_enum` and `add_enum_options` to add an enum and enum options to your metadata schema.

| Key  | Description                                    | Display Benefits                                      |
| ---- | ---------------------------------------------- | ----------------------------------------------------- |
| enum | Enumerated type with predefined set of values. | Facilitates categorical filtering and data validation |

Use `add_embedding` to add an embedding to your metadata schema.

| Key       | Description                                | Display Benefits                                                                        |
| --------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
| embedding | 1 to 4096 for Index. 1 to 2000 for Active. | Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon) |

Use `add_geospatial` to add a new geospatial type to the metadata schema.

| Key        | Description                                                                                                                                                                        | Display Benefits                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| geospatial | Geospatial data that contains latitude and longitude information. Latitude values are between +90 (North) to -90 (South). Longitude values are between +180 (West) to -180 (East). | Filtering data by using a geospatial map. |

<Note>
  * Geospatial custom metadata is supported only in Index.

  * Geospatial custom metadata can be applied to all data unit types and on individual frames in videos.
</Note>

<Warning>
  Incorrectly specifying a data type in the schema can cause errors when filtering your data in Index or Active. If you encounter errors while filtering, verify your schema is correct. If your schema has errors, correct the errors, re-import the schema, and then re-sync your Active Project.
</Warning>

### Import your metadata schema to Encord

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("metadata_1", data_type="boolean")
  metadata_schema.add_scalar("metadata_2", data_type="datetime")
  metadata_schema.add_scalar("metadata_3", data_type="number")
  metadata_schema.add_scalar("metadata_4", data_type="uuid")
  metadata_schema.add_scalar("metadata_5", data_type="varchar")
  metadata_schema.add_scalar("metadata_6", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("my-enum", values=["enum-value-01", "enum-value-02", "enum-value-03"])

  # Add embedding fields
  metadata_schema.add_embedding("my-test-active-embedding", size=512)
  metadata_schema.add_embedding("my-test-index-embedding", size=<values-from-1-to-4096>)

  # Add geospatial
  metadata_schema.add_geospatial("geo-point")

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("G2G", data_type="boolean")
  metadata_schema.add_scalar("Date", data_type="datetime")
  metadata_schema.add_scalar("Cost", data_type="number")
  metadata_schema.add_scalar("Priority", data_type="number")
  metadata_schema.add_scalar("ID-Sys-01", data_type="uuid")
  metadata_schema.add_scalar("ID-Sys-02", data_type="uuid")
  metadata_schema.add_scalar("Description", data_type="varchar")
  metadata_schema.add_scalar("Location", data_type="varchar")
  metadata_schema.add_scalar("Address", data_type="varchar")
  metadata_schema.add_scalar("Translation en-gb", data_type="text")
  metadata_schema.add_scalar("Translation en-ca", data_type="text")
  metadata_schema.add_scalar("Translation en-us", data_type="text")
  metadata_schema.add_scalar("Translation zh-tw", data_type="text")
  metadata_schema.add_scalar("Translation zh-hk", data_type="text")
  metadata_schema.add_scalar("Translation zh-cn", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("ready", values=["ripe", "partially-ripe", "unripe"])
  metadata_schema.add_enum("Fruit", values=["Blueberries", "Cherries", "Apples", "Kiwi"])

  # Add embedding fields
  metadata_schema.add_embedding("active-embedding-01", size=512)
  metadata_schema.add_embedding("active-embedding-02", size=512)
  metadata_schema.add_embedding("index-embedding-100", size=100)
  metadata_schema.add_embedding("index-embedding-1000", size=1000)

  # Add geospatial
  metadata_schema.add_geospatial("Coordinates")

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

### Verify your schema

After importing your schema to Encord we recommend that you verify that the import is successful. Run the following code to verify your metadata schema imported and that the schema is correct.

<CodeGroup>
  ```python Verify schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Verify your schema example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

### Update Custom Metadata (JSON)

When updating custom metadata using a JSON file, you **MUST** specify `"skip_duplicate_urls": true` and `"upsert_metadata": true`.

Specifying the `"skip_duplicate_urls": true` and `"upsert_metadata": true` flags in the JSON file does the following:

* New files registered with Encord and custom metadata for those files is added.

* Existing files have their existing custom metadata overwritten with the custom metadata specified in the JSON file.

**To update custom metadata with a JSON file:**

1. Create a registration [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) with the updated custom metadata. Include the `"skip_duplicate_urls": true` and `"upsert_metadata": true` flags.

<Note>
  * Custom metadata updates require `"skip_duplicate_urls": true` to function. It does not work if `"skip_duplicate_urls": false`.
  * Only custom metadata for pre-existing files is updated. Any new files present in the JSON are uploaded.
</Note>

```json Update custom metadata example theme={"dark"}
{
  "videos": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-custom-video-title.mp4",
      "clientMetadata": {"optional": "metadata"}
    }
  ],
  "skip_duplicate_urls": true,
  "upsert_metadata": true
}
```

2. Register your files with Encord using the new JSON file.

***

## Custom Embeddings

<Note>
  Metadata schemas, including custom embeddings, can only be imported through the Encord SDK.
</Note>

Encord enables the use of custom embeddings for images, image sequences, image groups, and individual video frames.

<Note>
  To learn how to use custom embeddings in Encord, see our [documentation here](/platform-documentation/Curate/custom-embeddings).
</Note>

### Step 1: Create a New Embedding Type

A key is required in your custom metadata schema for your embeddings. You can use any string as the key for your embeddings. We strongly recommend that you use a string that is meaningful.

If you do not include a key in your metadata schema, your imported embeddings are treated as strings.

<Tip>Embedding key names can contain alphanumeric (a-z, A-Z, 0-1) characters, hyphens, and underscores.</Tip>

Use `add_embedding` to add an embedding to your metadata schema.

<Info>
  We currently support embeddings of:

  * 1 to 4,096 dimensions for data curation.
  * 1 to 2,000 dimensions for label validation.
</Info>

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()


  # Add embedding fields
  metadata_schema.add_embedding('my-test-active-embedding', size=512)
  metadata_schema.add_embedding('my-test-index-embedding', size=<values-from-1-to-4096>)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()


  # Add embedding fields
  metadata_schema.add_embedding('active-embedding-01', size=512)
  metadata_schema.add_embedding('active-embedding-02', size=512)
  metadata_schema.add_embedding('index-embedding-100', size=100)
  metadata_schema.add_embedding('index-embedding-1000', size=1000)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

### Step 2: Upload Embeddings

With the key in the custom metadata schema ready, we can now import our embeddings.

Custom embedding sizes are flexible and can be set anywhere between 1 and 4096.

You can import embeddings after you have added your data or during your data registration.

<Note>Your key frames (frames specified with or without embeddings) always appear in Encord, regardless of what sampling rate you specify.</Note>

<Tip>Embedding key names can contain alphanumeric (a-z, A-Z, 0-1) characters, hyphens, and underscores.</Tip>

If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

<Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video.</Info>

<AccordionGroup>
  <Accordion title="Import while registering videos">
    #### Import while importing videos

    This JSON file imports embeddings while registering your data with Encord from a cloud integration.

    `config` is optional when importing your custom embeddings:

    ```json theme={"dark"}
    "config": {
        "sampling_rate": "<samples-per-second>",
        "keyframe_mode": "frame" or "seconds",
    },
    ```

    If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

    <Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video.</Info>

    <CodeGroup>
      ```json Import Embeddings Template theme={"dark"}

      {
          "videos": [
              {
                  "objectUrl": "<cloud-file-path-to-your-video-1>",
                  "title": "<title-for-your-video-1>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<samples-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "<cloud-file-path-to-your-video-2>",
                  "title": "<title-for-your-vide-2>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<frames-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "<cloud-path-to-your-video-3>",
                  "title": "<title-for-your-video-3>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<frames-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```

      ```json Example - Simple theme={"dark"}
      {
          "videos": [
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-001.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "111": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "113": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-002.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "157": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "257": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-003.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "11": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "13": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```

      ```json Example - Advanced theme={"dark"}
      {
          "videos": [
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-001.mp4",
                  "title": "awesome-video-001.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "111": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "113": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-002.mp4",
                  "title": "awesome-video-002.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "3",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "157": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "257": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-003.mp4",
                  "title": "awesome-video-003.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "4",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "11": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "13": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update specific videos">
    #### Update specific videos

    <CodeGroup>
      ```python Boilerplate theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

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

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "<data-hash-1>": {
              "$encord": {
                  "frames": {
                      "<frame-number-1>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      },
                      "<frame-number-2>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "<data-hash-2>": {
              "$encord": {
                  "config": {
                      "sampling_rate": <samples-per-second>,  # VIDEO ONLY (optional default = 1 sample/second)
                      "keyframe_mode": "frame" or "seconds",  # VIDEO ONLY (optional default = "frame")
                  },
                  "frames": {
                      "<frame-number-1>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      },
                      "<frame-number-2>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)
      ```

      ```python Example - Simple theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

      # Authentication
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "f2155fa4-6040-408a-84d5-72bacb4f45db": {
              "$encord": {
                  "frames": {
                      "113": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "131": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "f235ad84-f9eb-4dc1-934d-d05e1cd70e59": {
              "$encord": {
                  "frames": {
                      "171": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "231": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)

      ```

      ```python Example - Advanced theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

      # Authentication
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "6b8d797a-4655-43c3-b251-cbd6cc995bc6": {
              "$encord": {
                  "config": {
                      "sampling_rate": 0,  # VIDEO ONLY (optional default = 1 sample/second)
                  },
                  "frames": {
                      "111": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "222": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "d9185f6e-3dbc-443b-bd37-77b2f34f157e": {
              "$encord": {
                  "config": {
                      "sampling_rate": 2,  # VIDEO ONLY (optional default = 1 sample/second)
                      "keyframe_mode": "frame",  # VIDEO ONLY (optional default = "frame")
                  },
                  "frames": {
                      "333": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "444": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Import while registering data units">
    #### Import while importing data units

    This JSON file imports embeddings while registering your data with Encord from a cloud integration.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/data-unit/file-name-01.file-extension",
            "title": "data-unit-title.file-extension",
            "clientMetadata": {"metadata-1": "value", "metadata-2": "value"}
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Example - Simple theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 01",
            "clientMetadata": {
              "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-02.jpg",
            "title": "Blueberry 02",
            "clientMetadata": {
              "embeddings-10": [0.44531257187793305, 0.22303790771089994, 0.1101464760810051, 0.3898273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 03",
            "clientMetadata": {
              "embeddings-10": [0.45631257187793305, 0.23403790771089994, 0.1211464760810051, 0.3678273275803421, 0.06849531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                }
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Example - Advanced theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-01.jpg",
            "title": "Cherry 01",
            "clientMetadata": {
              "Dark": false,
              "Location": "NY",
              "Date": "2024-06-13",
              "ACME Co ID": "8ada6567-c034-4bd4-91d0-04dab5d729d5",
              "Priority": "1",
              "embeddings-10": [
                0.67831257187793305,
                0.32603790771089994,
                0.4341464760810051,
                0.9748273275803421,
                0.23549531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-02.jpg",
            "title": "Cherry 02",
            "clientMetadata": {
              "Dark": false,
              "Location": "NY",
              "Date": "2024-06-13",
              "ACME Co ID": "1262bf57-402e-427c-8c60-276df65513ea",
              "Priority": "1",
              "embeddings-10": [
                0.42531257187793305,
                0.33403790771089994,
                0.5671464760810051,
                0.3688273275803421,
                0.06849531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-03.jpg",
            "title": "Cherry 03",
            "clientMetadata": {
              "Dark": true,
              "Location": "OH",
              "Date": "2024-06-13",
              "ACME Co ID": "3000919f-01e2-4574-a4fd-a2790c4f7b8b",
              "Priority": "2",
              "embeddings-10": [
                0.22231257187793305,
                0.44503790771089994,
                0.7341464760810051,
                0.8368273275803421,
                0.06849531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update specific data units">
    #### Import specific data units

    The custom embeddings format for images, text files, PDFs, and audio files follows the same format as [importing custom metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata#folders-and-custom-metadata).

    ```python theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient
    from encord.http.bundle import Bundle

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

    # Authenticate with Encord using the path to your private key
    user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=SSH_PATH,
    )

    # Define a dictionary with item UUIDs and their respective metadata updates
    updates = {
        "<data-ID-1>": {"<my-embedding>": [1.0, 2.0, 3.0]},
        "<data-ID-2>": {"<my-embedding>": [1.0, 2.0, 3.0]}
    }

    # Use the Bundle context manager
    with Bundle() as bundle:
        # Update the storage items based on the dictionary
        for item_uuid, metadata_update in updates.items():
            item = user_client.get_storage_item(item_uuid=item_uuid)

            # Make a copy of the current metadata and update it with the new metadata
            curr_metadata = item.client_metadata.copy()
            curr_metadata.update(metadata_update)

            # Update the item with the new metadata and bundle
            item.update(client_metadata=curr_metadata, bundle=bundle)

    ```
  </Accordion>
</AccordionGroup>

***

## How To Increase File Registration Speed

To speed up file registration with Encord, you can include metadata for each file in the upload JSON. This metadata is used directly without additional validation and is not stored on our servers. **Ensuring accuracy in the metadata you provide is essential to maintain precise labels.**

<Warning>
  The metadata referenced here is distinct from `clientMetadata` and serves a different purpose. Documentation for `clientMetadata` can be found [here](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).
</Warning>

* **`imageMetadata`** for images:
  * `mimeType`: MIME type of the image (e.g., `image/jpeg`).
  * `fileSize`: Size of the file in bytes.
  * `width`: Width of the image in pixels.
  * `height`: Height of the image in pixels.

* **`audioMetadata`** for audio files:
  * `duration_seconds` (float): Audio duration in seconds.
  * `file_size` (int): Size of the audio file in bytes.
  * `mime_type` (str): MIME type (e.g., `audio/mpeg`, `audio/wav`).
  * `sample_rate` (int): Sample rate in Hz.
  * `bit_depth` (int): Size of each sample in bits.
  * `codec` (str): Codec used (e.g., `mp3`, `pcm`).
  * `num_channels` (int): Number of audio channels.

* **`videoMetadata`** for videos:
  * `fps`: Frames per second.
  * `duration`: Duration in seconds.
  * `width` / `height`: Dimensions in pixels.
  * `file_size`: File size in bytes.
  * `mime_type`: File type (MIME standard).

<CodeGroup>
  ```json imageMetadata theme={"dark"}
  {
    "images": [
      {
        "objectUrl": "s3://my_image.jpg",
        "imageMetadata": {
          "mimeType": "image/jpg",
          "fileSize": 124,
          "width": 640,
          "height": 480
        }
      }
    ]
  }
  ```

  ```json audioMetadata theme={"dark"}
  {
      "audio": [
        {
          "objectUrl": "audio_file.mp3",
          "audioMetadata": {
              "duration": 23.98,
              "file_size": 2900000,
              "mime_type": "audio/mp3",
              "sample_rate": 44100,
              "bit_depth": 24,
              "codec": "mp3",
              "num_channels": 2
          }
        }
      ]
  }
  ```

  ```json videoMetadata theme={"dark"}
  {
    "videos": [
      {
        "objectUrl": "<object url_1>",
        "videoMetadata": {
              "fps": 23.98,
              "duration": 29.09,
              "width": 1280,
              "height": 720,
              "file_size": 5468354,
              "mime_type": "video/mp4"
          }
      }
    ]
  }
  ```
</CodeGroup>

***

## Check Data Registration Status

You can check the progress of the processing job by clicking the bell icon in the top right corner of the Encord app.

* A spinning progress indicator shows that the processing job is still in progress.
* If successful, the processing completes with a green tick icon.
* If unsuccessful, there is  a red cross icon, as seen below.

<div>
  <img />
</div>

If the upload is unsuccessful, ensure that:

* Your provider permissions are set correctly
* The object data format is supported
* The upload JSON or CSV file is correctly formatted.

<Tip>
  Check which files failed to upload by clicking the *Export* icon to download a CSV log file. Every row in the CSV corresponds to a file which failed to be uploaded.
</Tip>

<Note>You only see failed uploads if the **Ignore individual file errors** toggle was not enabled during cloud data registration.</Note>

***

## Helpful Scripts and Examples

Use the following examples and helpful scripts to quickly learn how to create JSON and CSV files formatted for uploading cloud data to Encord, by constructing the URLs from the specified path in your private storage.

<AccordionGroup>
  <Accordion title="AWS S3">
    AWS S3 object URLs can follow a few set [patterns](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html):

    * **Virtual-hosted style**: `https://<bucket-name>.s3.<region>.amazonaws.com/<key-name>`
    * **Path-style**: `https://s3.<region>.amazonaws.com/<bucket-name>/<key-name>`
    * **S3 protocol**: `S3://<bucket-name>/<key-name>`
    * **Legacy**: those without regions or those with `S3-<region>` in the URL

    AWS best practice is to use [Virtual-hosted style](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html). Path-style is [planned to be deprecated](https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/) and the legacy URLs are already deprecated.

    We support Virtual-hosted style, Path-style and S3 protocol object URLs. We recommend you use Virtual-hosted style object URLs wherever possible.

    Object URLs can be found in the *Properties* tab of the object in question. Navigate to AWS S3 **>** *bucket* **>**  *object* **>** Properties to find the *Object URL*.

    <img />

    Here's a python script which creates a JSON file for single images by constructing the URLs from the specified path in a given S3 bucket. You'll need to configure the following variables to match your setup.

    1. **region**: the AWS region where your S3 bucket is.
    2. **aws\_profile**: the name of the profile in the AWS \~/.aws/credentials file. See [AWS Credentials Documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) to properly set up the credentials file.
    3. **bucket\_name**: the name of your S3 bucket you want to pull files from.
    4. **s3\_directory**: the path to the directory in the S3 bucket where your files are stored.

    In this Amazon S3 Virtual-hosted style URLs example, `my-bucket` is the bucket name,
    `us-west-2` is the region, and `images/dogs` is the S3 directory:

    ```text theme={"dark"}
    https://my-bucket.s3.us-west-2.amazonaws.com/images/dogs/puppy.png
    ```

    And the script itself:

    ```python theme={"dark"}
    import boto3
    import json
    from pathlib import Path
    region = 'FILL_ME_IN'
    aws_profile = 'FILL_ME_IN'
    bucket_name = 'FILL_ME_IN'
    s3_directory = Path('FILL_ME_IN')
    root_url = f'https://{bucket_name}.s3.{region}.amazonaws.com'
    session = boto3.Session(profile_name=aws_profile)
    s3 = boto3.resource('s3')
    bucket = s3.Bucket(bucket_name)
    images = []
    for object_summary in bucket.objects.filter(Prefix=s3_directory.as_posix() + '/'):
        object_file = Path(object_summary.key)
        if object_file.parent == s3_directory:
            object_url = f'{root_url}/{object_summary.key}'
            images.append({'objectUrl': object_url})
    data_dict = {'images': images}
    output_file = Path('upload_images.json')
    output_file.write_text(json.dumps(data_dict, indent=2))
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="GCP Storage">
    The following Python scripts generate a JSON file for uploading cloud data to Encord, specifically for a designated GCP Storage bucket. The resulting JSON file includes images, videos, audio, pdfs, and text files.

    There are two scripts below. The first script only shares the assets' links and optional client metadata. The second, recommend approach also includes asset metadata for quicker file uploads (as well as preventing ingestion costs from your cloud provider).

    <Warning>To run these scripts, you must have [gsutil](https://cloud.google.com/storage/docs/gsutil) installed.</Warning>

    Before using the scripts, make sure to:

    * Specify your bucket name in the `bucket_name` variable.
    * Decide which [GCP authentication](https://cloud.google.com/docs/authentication/gcloud) method to use. There are 3 options:
      * Option 1:  Hard code the [service account authentication JSON](https://cloud.google.com/iam/docs/keys-create-delete#iam-service-account-keys-create-console).
      * Option 2: Create a `.json` file on your computer and provide the path to the [service account authentication JSON](https://cloud.google.com/iam/docs/keys-create-delete#iam-service-account-keys-create-console).
      * Option 3: If you are already authenticated with gcloud CLI the script gets the credentials from your environment.
    * Optionally, modify the name of the output file, currently set to `json_upload_for_encord.json`.

    <CodeGroup>
      ```python Simple Registration theme={"dark"}
      import json
      from pathlib import Path
      from typing import TypedDict, Optional
      from google.cloud import storage
      from google.oauth2 import service_account
      import typer
      from typer import Argument, Option

      app = typer.Typer()

      # Authenticate with GCP
      # OPTION 1: Get GCP credentials from the JSON
      service_account_info = {
          "type": "service_account",
          "project_id": "your_google_service_project_id",
          "private_key_id": "your_google_secrets_private_key_id",
          "private_key": "your_google_secrets_private_key",
          "client_email": "your_client_email",
          "client_id": "your_client_id",
          "auth_uri": "https://accounts.google.com/o/oauth2/auth",
          "token_uri": "https://oauth2.googleapis.com/token",
          "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
          "client_x509_cert_url": "..."
      }


      class Entry(TypedDict):
          objectUrl: str
          title: str
          clientMetadata: dict

      @app.command()
      def main(
          bucket_name: str = Argument(..., help="Name of the GCS bucket"),
          bucket_folder: str = Option("", "--bucket-folder", "-f", help="Folder path within the bucket"),
          output_path: str = Option("json_upload_for_encord.json", "--output", "-o", help="Output JSON filename"),
          output_dir: str = Option(".", "--output-dir", "-d", help="Output directory path"),
          service_account_info: Optional[str] = Option(None, "--service-account-info", help="Service account JSON"),
          service_account_file: Optional[str] = Option(None, "--service-account", "-s", help="Path to service account JSON file"),
          add_custom_metadata: bool = Option(False, "--custom-metadata", help="Add custom metadata (you can modify the function)"),
          skip_duplicates: bool = Option(True, "--skip-duplicates/--no-skip-duplicates", help="Skip duplicate URLs in output")
      ) -> None:
          """
          Generate JSON upload file for Encord from GCS bucket contents.

          Example usage:
          python create_json_upload.py my-bucket --bucket-folder my/folder
          python create_json_upload.py my-bucket -f data/images -o output.json
          """

          # Convert output_dir string to Path
          outpath = Path(output_dir)

          print(f"Processing bucket: {bucket_name}")
          if bucket_folder:
              print(f"Folder: {bucket_folder}")

          # Get credentials from authentication JSON
          credentials = None
          if service_account_info:
              try:
                  credentials = service_account.Credentials.from_service_account_info(json.loads(service_account_info))
                  print("Using service account from provided JSON string.")
              except (json.JSONDecodeError, Exception) as e:
                  print(f"Failed to load service account from string: {e}")
                  raise typer.Exit(code=1)
          elif service_account_file:
              try:
                  credentials = service_account.Credentials.from_service_account_file(service_account_file)
                  print(f"Using service account from: {service_account_file}")
              except Exception as e:
                  print(f"Failed to load service account file: {e}")
                  raise typer.Exit(code=1)

          # Instantiate storage client
          try:
              if credentials:
                  storage_client = storage.Client(credentials=credentials)
              else:
                  storage_client = storage.Client()
                  print("Using default credentials")
          except Exception as auth_error:
              print(
                  "Authentication failed. Try one of the following:\n"
                  "1. Run: gcloud auth application-default login\n"
                  "2. Use --service-account flag with path to service account JSON\n"
                  "3. Set GOOGLE_APPLICATION_CREDENTIALS environment variable"
              )
              print(f"Error: {auth_error}")
              raise typer.Exit(code=1)

          # Access the bucket
          try:
              bucket = storage_client.get_bucket(bucket_name)
          except Exception as e:
              print(f"Failed to access bucket '{bucket_name}'. Make sure it exists and you have permission.")
              print(f"Error: {e}")
              raise typer.Exit(code=1)

          # Ensure the folder path ends with a slash if it's not empty
          if bucket_folder and not bucket_folder.endswith('/'):
              bucket_folder = f"{bucket_folder}/"

          print(f"Fetching objects from bucket: {bucket_name}, folder: {bucket_folder or '(root)'}")

          # Get all blobs with the specified folder prefix
          blobs = bucket.list_blobs(prefix=bucket_folder)
          outpath.mkdir(parents=True, exist_ok=True)

          videos: list[Entry] = []
          images: list[Entry] = []
          audio: list[Entry] = []
          text: list[Entry] = []
          pdfs: list[Entry] = []

          # File extension mappings
          image_extensions = {'.png', '.jpg', '.jpeg', '.tiff'}
          video_extensions = {'.mp4', '.mov', '.webm'}
          audio_extensions = {'.mp3', '.wav', '.m4a'}
          text_extensions = {'.txt'}
          pdf_extensions = {'.pdf'}

          processed_count = 0
          skipped_count = 0

          for blob in blobs:
              # Skip directory markers
              if blob.name.endswith("/"):
                  skipped_count += 1
                  continue

              # Skip if the blob is not actually in the specified folder (prevents partial prefix matches)
              if bucket_folder and not blob.name.startswith(bucket_folder):
                  skipped_count += 1
                  continue

              p = Path(blob.name)

              # Generate client metadata
              client_metadata = {}

              # Add custom metadata based on your needs
              if add_custom_metadata:
                  # You can modify this function to add your own metadata
                  client_metadata = generate_custom_metadata(blob.name)

              # Build the GCS URL
              gs_url = f"gs://{bucket_name}/{blob.name}"
              file_name = p.name
              suffix_lower = p.suffix.lower()

              entry = Entry(
                  objectUrl=gs_url,
                  title=file_name,
                  clientMetadata=client_metadata
              )

              # Categorize by file type
              if suffix_lower in video_extensions:
                  videos.append(entry)
                  processed_count += 1
              elif suffix_lower in image_extensions:
                  images.append(entry)
                  processed_count += 1
              elif suffix_lower in audio_extensions:
                  audio.append(entry)
                  processed_count += 1
              elif suffix_lower in text_extensions:
                  text.append(entry)
                  processed_count += 1
              elif suffix_lower in pdf_extensions:
                  pdfs.append(entry)
                  processed_count += 1
              else:
                  print(f"  Unknown file type: {p.suffix} ({file_name})")
                  skipped_count += 1

          # Create output JSON
          output_data = {
              "images": images,
              "videos": videos,
              "audio": audio,
              "text": text,
              "pdfs": pdfs,
              "skip_duplicate_urls": skip_duplicates
          }

          # Save results to JSON
          output_file = outpath / output_path
          output_file.write_text(json.dumps(output_data, indent=4))

          print(f"\nJSON file saved to: {output_file.absolute()}")

      def generate_custom_metadata(blob_name: str) -> dict:
          """
          Custom function to generate metadata based on blob name.
          Modify this function based on your needs.
          """
          metadata = {}

          # Example: Add file path components as metadata
          p = Path(blob_name)
          if len(p.parts) > 1:
              metadata["folder"] = str(p.parent)

          # Add more custom logic here as needed
          # For example:
          # - Extract date from filename
          # - Add tags based on folder structure
          # - Parse metadata from filename patterns

          return metadata


      if __name__ == "__main__":
          app()
      ```

      ```python Registration with Asset Metadata (Faster) theme={"dark"}
      import json
      from pathlib import Path
      from typing import TypedDict, Optional
      from google.cloud import storage
      from google.oauth2 import service_account
      import typer
      from typer import Argument, Option

      app = typer.Typer()


      class ImageMetadata(TypedDict, total=False):
          mimeType: str
          fileSize: int
          width: int
          height: int


      class VideoMetadata(TypedDict, total=False):
          fps: float
          duration: float
          width: int
          height: int
          file_size: int
          mime_type: str


      class AudioMetadata(TypedDict, total=False):
          duration: float
          file_size: int
          mime_type: str
          sample_rate: int
          bit_depth: int
          codec: str
          num_channels: int


      class TextMetadata(TypedDict, total=False):
          fileSize: int
          mime_type: str


      class PDFMetadata(TypedDict, total=False):
          fileSize: int
          numPages: int


      class Entry(TypedDict, total=False):
          objectUrl: str
          title: str
          clientMetadata: dict
          imageMetadata: ImageMetadata
          videoMetadata: VideoMetadata
          audioMetadata: AudioMetadata
          textMetadata: TextMetadata
          pdfMetadata: PDFMetadata


      def get_image_metadata(blob: storage.Blob, fetch_dimensions: bool = False) -> ImageMetadata:
          """Extract metadata for image files."""
          metadata = ImageMetadata(
              mimeType=blob.content_type or f"image/{Path(blob.name).suffix[1:]}",
              fileSize=blob.size
          )

          if fetch_dimensions:
              try:
                  # Optional: Download and analyze image to get dimensions
                  # This requires PIL/Pillow: pip install Pillow
                  from PIL import Image
                  import io

                  image_bytes = blob.download_as_bytes()
                  with Image.open(io.BytesIO(image_bytes)) as img:
                      metadata["width"] = img.width
                      metadata["height"] = img.height
              except ImportError:
                  print("  ⚠️  Install Pillow for image dimensions: pip install Pillow")
              except Exception as e:
                  print(f"  ⚠️  Could not get image dimensions: {e}")

          return metadata


      def get_video_metadata(blob: storage.Blob, fetch_details: bool = False) -> VideoMetadata:
          """Extract metadata for video files."""
          metadata = VideoMetadata(
              file_size=blob.size,
              mime_type=blob.content_type or f"video/{Path(blob.name).suffix[1:]}"
          )

          if fetch_details:
              try:
                  # Optional: Download and analyze video to get detailed metadata
                  # This requires ffmpeg-python: pip install ffmpeg-python
                  import ffmpeg
                  import tempfile

                  with tempfile.NamedTemporaryFile(suffix=Path(blob.name).suffix) as tmp_file:
                      blob.download_to_filename(tmp_file.name)

                      probe = ffmpeg.probe(tmp_file.name)
                      video_stream = next((stream for stream in probe['streams'] if stream['codec_type'] == 'video'), None)

                      if video_stream:
                          metadata["width"] = int(video_stream['width'])
                          metadata["height"] = int(video_stream['height'])

                          # Calculate FPS
                          if 'r_frame_rate' in video_stream:
                              fps_fraction = video_stream['r_frame_rate'].split('/')
                              if len(fps_fraction) == 2:
                                  metadata["fps"] = float(fps_fraction[0]) / float(fps_fraction[1])

                          # Get duration
                          if 'duration' in video_stream:
                              metadata["duration"] = float(video_stream['duration'])
                          elif 'duration' in probe.get('format', {}):
                              metadata["duration"] = float(probe['format']['duration'])

              except ImportError:
                  print("  ⚠️  Install ffmpeg-python for video details: pip install ffmpeg-python")
                  print("     Also ensure ffmpeg is installed on your system")
              except Exception as e:
                  print(f"  ⚠️  Could not get video details for {blob.name}: {e}")

          return metadata


      def get_default_bit_depth(mime_type: str, codec: str) -> int:
          """Get reasonable default bit depth by format."""

          # Lossy formats - typically 16-bit equivalent
          if codec in ['mp3', 'aac', 'm4a', 'ogg', 'wma']:
              return 16

          # Lossless formats - could be higher
          elif codec in ['flac', 'alac']:
              return 16  # Safe default, though could be 24

          # Uncompressed formats
          elif codec in ['wav', 'aiff']:
              return 16  # Most common, though could be 24 or 32

          # Professional/studio formats
          elif codec in ['dsd', 'dsf']:
              return 1  # DSD is 1-bit (special case)

          # Default fallback
          return 16

      def get_audio_metadata(blob: storage.Blob, fetch_details: bool = False) -> AudioMetadata:
          """Extract metadata for audio files."""
          metadata = AudioMetadata(
              file_size=blob.size,
              mime_type=blob.content_type or f"audio/{Path(blob.name).suffix[1:]}"
          )

          if fetch_details:
              try:
                  # Optional: Download and analyze audio to get detailed metadata
                  # This requires mutagen: pip install mutagen
                  from mutagen import File
                  import tempfile

                  with tempfile.NamedTemporaryFile(suffix=Path(blob.name).suffix) as tmp_file:
                      blob.download_to_filename(tmp_file.name)

                      audio_file = File(tmp_file.name)
                      if audio_file is not None:
                          # Duration
                          if hasattr(audio_file.info, 'length'):
                              metadata["duration"] = audio_file.info.length

                          # Sample rate
                          if hasattr(audio_file.info, 'sample_rate'):
                              metadata["sample_rate"] = audio_file.info.sample_rate

                          # Channels
                          if hasattr(audio_file.info, 'channels'):
                              metadata["num_channels"] = audio_file.info.channels

                          # Bit depth (not always available)
                          if hasattr(audio_file.info, 'bits_per_sample'):
                              metadata["bit_depth"] = audio_file.info.bits_per_sample
                          else:
                              metadata["bit_depth"] = 16 # Default

                          # Codec
                          suffix = Path(blob.name).suffix[1:].lower()
                          metadata["codec"] = suffix

              except ImportError:
                  print("  ⚠️  Install mutagen for audio details: pip install mutagen")
              except Exception as e:
                  print(f"  ⚠️  Could not get audio details for {blob.name}: {e}")

          return metadata


      def get_pdf_metadata(blob: storage.Blob, fetch_pages: bool = False) -> PDFMetadata:
          """Extract metadata for PDF files."""
          metadata = PDFMetadata(fileSize=blob.size)

          if fetch_pages:
              try:
                  # Optional: Download and analyze PDF to get page count
                  # This requires PyPDF2: pip install PyPDF2
                  import PyPDF2
                  import io

                  pdf_bytes = blob.download_as_bytes()
                  with io.BytesIO(pdf_bytes) as pdf_stream:
                      pdf_reader = PyPDF2.PdfReader(pdf_stream)
                      metadata["numPages"] = len(pdf_reader.pages)

              except ImportError:
                  print("  ⚠️  Install PyPDF2 for PDF page count: pip install PyPDF2")
              except Exception as e:
                  print(f"  ⚠️  Could not get PDF page count: {e}")

          return metadata


      def get_text_metadata(blob: storage.Blob) -> TextMetadata:
          """Extract metadata for text files."""
          return TextMetadata(
              fileSize=blob.size,
              mime_type=blob.content_type or "text/plain"
          )


      @app.command()
      def main(
              bucket_name: str = Argument(..., help="Name of the GCS bucket"),
              bucket_folder: str = Option("", "--bucket-folder", "-f", help="Folder path within the bucket"),
              output_path: str = Option("json_upload_for_encord.json", "--output", "-o", help="Output JSON filename"),
              output_dir: str = Option(".", "--output-dir", "-d", help="Output directory path"),
              service_account_file: Optional[str] = Option(None, "--service-account", "-s",
                                                           help="Path to service account JSON file"),
              service_account_info: Optional[str] = Option(None, "--service-account-info", help="Service account JSON"),
              add_shard_metadata: bool = Option(True, "--add-shard/--no-shard",
                                                help="Extract and add shard metadata from folder names"),
              add_custom_metadata: bool = Option(False, "--custom-metadata",
                                                 help="Add custom metadata (you can modify the function)"),
              skip_duplicates: bool = Option(True, "--skip-duplicates/--no-skip-duplicates",
                                             help="Skip duplicate URLs in output"),
              fetch_image_dimensions: bool = Option(False, "--image-dimensions",
                                                    help="Get image dimensions (requires Pillow)"),
              fetch_video_details: bool = Option(False, "--video-details",
                                                 help="Get video fps, duration, dimensions (requires ffmpeg-python)"),
              fetch_audio_details: bool = Option(False, "--audio-details",
                                                 help="Get audio sample rate, channels, etc (requires mutagen)"),
              fetch_pdf_pages: bool = Option(False, "--pdf-pages", help="Get PDF page count (requires PyPDF2)"),
              fetch_all_details: bool = Option(False, "--all-details",
                                               help="Fetch all available metadata (requires all optional packages)")
      ) -> None:
          """
          Generate JSON upload file for Encord from GCS bucket contents with metadata.

          Basic usage:
              python create_json_upload.py my-bucket --bucket-folder my/folder

          With rich metadata (requires optional packages):
              python create_json_upload.py my-bucket --all-details
              python create_json_upload.py my-bucket --image-dimensions --video-details

          Optional packages for rich metadata:
              pip install Pillow          # For image dimensions
              pip install ffmpeg-python   # For video details (also need ffmpeg installed)
              pip install mutagen         # For audio details
              pip install PyPDF2          # For PDF page counts

          Or install all:
              pip install Pillow ffmpeg-python mutagen PyPDF2
          """

          # Handle --all-details flag
          if fetch_all_details:
              fetch_image_dimensions = True
              fetch_video_details = True
              fetch_audio_details = True
              fetch_pdf_pages = True

          # Convert output_dir string to Path
          outpath = Path(output_dir)

          print(f"Processing bucket: {bucket_name}")
          if bucket_folder:
              print(f"Folder: {bucket_folder}")

          # Load credentials if a path is provided
          credentials = None
              try:
                  credentials = service_account.Credentials.from_service_account_info(json.loads(service_account_info))
                  print("Using service account from provided JSON string.")
              except (json.JSONDecodeError, Exception) as e:
                  print(f"Failed to load service account from string: {e}")
                  raise typer.Exit(code=1)
          elif service_account_file:
              try:
                  credentials = service_account.Credentials.from_service_account_file(service_account_file)
                  print(f"Using service account from: {service_account_file}")
              except Exception as e:
                  print(f"Failed to load service account file: {e}")
                  raise typer.Exit(code=1)

          # Instantiate storage client
          try:
              if credentials:
                  storage_client = storage.Client(credentials=credentials)
              else:
                  storage_client = storage.Client()
                  print("Using default credentials")
          except Exception as auth_error:
              print(
                  "Authentication failed. Try one of the following:\n"
                  "1. Run: gcloud auth application-default login\n"
                  "2. Use --service-account flag with path to service account JSON\n"
                  "3. Set GOOGLE_APPLICATION_CREDENTIALS environment variable"
              )
              print(f"Error: {auth_error}")
              raise typer.Exit(code=1)

          # Access the bucket
          try:
              bucket = storage_client.get_bucket(bucket_name)
          except Exception as e:
              print(f"Failed to access bucket '{bucket_name}'. Make sure it exists and you have permission.")
              print(f"Error: {e}")
              raise typer.Exit(code=1)

          # Ensure the folder path ends with a slash if it's not empty
          if bucket_folder and not bucket_folder.endswith('/'):
              bucket_folder = f"{bucket_folder}/"

          print(f"Fetching objects from bucket: {bucket_name}, folder: {bucket_folder or '(root)'}")

          # Get all blobs with the specified folder prefix
          blobs = list(bucket.list_blobs(prefix=bucket_folder))
          outpath.mkdir(parents=True, exist_ok=True)

          videos: list[Entry] = []
          images: list[Entry] = []
          audio: list[Entry] = []
          text: list[Entry] = []
          pdfs: list[Entry] = []

          # File extension mappings
          image_extensions = {'.png', '.jpg', '.jpeg', '.tiff'}
          video_extensions = {'.mp4', '.mov', '.webm'}
          audio_extensions = {'.mp3', '.wav', '.m4a'}
          text_extensions = {'.txt'}
          pdf_extensions = {'.pdf'}

          processed_count = 0
          skipped_count = 0

          print(f"Found {len(blobs)} objects to process...")

          for i, blob in enumerate(blobs, 1):
              # Skip directory markers
              if blob.name.endswith("/"):
                  skipped_count += 1
                  continue

              # Skip if the blob is not actually in the specified folder (prevents partial prefix matches)
              if bucket_folder and not blob.name.startswith(bucket_folder):
                  skipped_count += 1
                  continue

              p = Path(blob.name)

              # Generate client metadata
              client_metadata = {}

              # Add custom metadata based on your needs
              if add_custom_metadata:
                  client_metadata = generate_custom_metadata(blob.name)

              # Try to extract shard from parent folder name
              if add_shard_metadata:
                  try:
                      shard = int(p.parent.name)
                      client_metadata["shard"] = shard
                  except (ValueError, AttributeError):
                      pass

              # Build the GCS URL
              gs_url = f"gs://{bucket_name}/{blob.name}"
              file_name = p.name
              suffix_lower = p.suffix.lower()

              # Base entry
              entry: Entry = {
                  "objectUrl": gs_url,
                  "title": file_name,
                  "clientMetadata": client_metadata
              }

              # Categorize by file type and add appropriate metadata
              if suffix_lower in video_extensions:
                  entry["videoMetadata"] = get_video_metadata(blob, fetch_video_details)
                  videos.append(entry)
                  processed_count += 1
              elif suffix_lower in image_extensions:
                  entry["imageMetadata"] = get_image_metadata(blob, fetch_image_dimensions)
                  images.append(entry)
                  processed_count += 1
              elif suffix_lower in audio_extensions:
                  entry["audioMetadata"] = get_audio_metadata(blob, fetch_audio_details)
                  audio.append(entry)
                  processed_count += 1
              elif suffix_lower in text_extensions:
                  entry["textMetadata"] = get_text_metadata(blob)
                  text.append(entry)
                  processed_count += 1
              elif suffix_lower in pdf_extensions:
                  entry["pdfMetadata"] = get_pdf_metadata(blob, fetch_pdf_pages)
                  pdfs.append(entry)
                  processed_count += 1
              else:
                  print(f"  Unknown file type: {p.suffix} ({file_name})")
                  skipped_count += 1

          # Create output JSON
          output_data = {
              "images": images,
              "videos": videos,
              "audio": audio,
              "text": text,
              "pdfs": pdfs,
              "skip_duplicate_urls": skip_duplicates
          }

          # Save results to JSON
          output_file = outpath / output_path
          output_file.write_text(json.dumps(output_data, indent=4))

          print(f"\nJSON file saved to: {output_file.absolute()}")


      def generate_custom_metadata(blob_name: str) -> dict:
          """
          Custom function to generate metadata based on blob name.
          Modify this function based on your needs.
          """
          metadata = {}

          # Example: Add file path components as metadata
          p = Path(blob_name)
          if len(p.parts) > 1:
              metadata["folder"] = str(p.parent)

          # Add more custom logic here as needed
          # For example:
          # - Extract date from filename
          # - Add tags based on folder structure
          # - Parse metadata from filename patterns

          return metadata


      if __name__ == "__main__":
          app()
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## FAQ

**What happens to the data hash of a file when replacing files?**

For example, if we submit a labeling task to an Encord Project, associated with an image (a data hash on Encord) stored in an integrated S3 bucket.

What happens when we update/replace that image in the S3 bucket using the same name? Does the data hash (and thus the associated labeling task) now automatically point to the new image?

The data hash is tied to the storage item record, not the file contents. This means replacing an image in S3 at the same path does not affect it or the associated labeling task. Encord generates signed URLs dynamically from the stored S3 path, so the updated file is served automatically with no action needed on the Encord side.

However, if S3 object versioning is enabled on your bucket, the signed URL may still resolve to the original version rather than the replacement.


# Cloud-Synced Data
Source: https://docs.encord.com/platform-documentation/Curate/add-files/index-register-cloud-data-cloud-sync



Cloud-synced folders automatically stay in sync with connected cloud storage, regularly updating to ensure all new and existing files are available in Encord without manual intervention. Registering your cloud data using Cloud-synced folders provides you with a very quick way of getting up and running.

<Note>[Custom Metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata) needs to be uploaded separately if you use this method to register your data with Encord.</Note>

## File Support and Limits

* Cloud-synced folders support images, videos, PDFs, text, HTML, and audio files.

<Note>Image groups, image sequences, and DICOM series are not currently supported by Cloud-synced folders.</Note>

* A single cloud synced folder can contain a maximum of 10 million files.

## Register Cloud Data using Cloud-synced Folders

### 1. Create an Integration

At least one [data integration](/platform-documentation/General/annotate-data-integrations) is required to register cloud data to Encord. Encord can integrate with the following cloud service providers:

|                                                                                                     |                                                                                                          |                                                                                                        |
| :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
| [AWS S3](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration)       | [Azure blob](/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration) | [GCP storage](/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration)     |
| [Open Telekom Cloud](/platform-documentation/General/annotate-data-integrations#open-telecom-cloud) | [Wasabi](/platform-documentation/General/annotate-data-integrations/annotate-wasabi-integration)         | [MinIO](/platform-documentation/General/annotate-data-integrations/annotate-minIO-integration)         |
| [Oracle](/platform-documentation/General/annotate-data-integrations/annotate-oracle-integration)    | [Cloudflare](/platform-documentation/General/annotate-data-integrations/annotate-cloudflare-integration) | [CoreWeave](/platform-documentation/General/annotate-data-integrations/annotate-coreweave-integration) |

### 2. Create a Cloud-synced Folder

<Warning>
  You cannot change URI after folder creation.
</Warning>

1. Go to **Data** > **Files & Folders**.

2. Click **New folder > Cloud-synced folder**.
   The *New Cloud-synced folder* dialog appears.

<div>
  <img />
</div>

3. Provide the following:

   * **Title:** Provide a meaningful name for the Cloud-synced folder.
   * **Description:** OPTIONAL - Provide a meaningful description for the Cloud-synced folder.
   * **Select your integration:** Select the integration to use from the drop down.
   * **Storage path:** Specify the storage/file path to your cloud storage. For example: `gs://encord-gcp-bucket/CloudSync/` or `s3://encord-aws-bucket/CloudSync`.
   * **Automatically sync data**: Automatically syncs data from your cloud storage to Encord once every 24 hours.
   * **Metadata ingestion**: Enable this toggle to import custom metadata files from your cloud storage. Set your sidecar suffix (default is `.metadata.json`). Any file matching that suffix is treated as metadata for its paired data file and does not appear as a separate item in your folder.

4. Click **Create**.
   The page for the new Cloud-synced folder appears.

#### Find Storage Path

Finding the Storage path for your folder or object varies across Cloud Storage platforms.

**AWS**

![Find AWS storage path](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/aws-storage-path.gif)

**GCP**

![Find GCP storage path](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/gcp-storage-path.gif)

### 3. Sync Data Between Encord and Cloud Storage

1. Go to **Data** > **Files & Folders**.
   The Cloud-synced folder page appears.

   ![Sync your Data](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/cloud-synced-folder-sync-cloud-data.gif)

2. Click into your cloud-synced folder.

   ![Sync your Data](https://storage.googleapis.com/docs-media.encord.com/E2E%20Artifacts/Screenshots/e2e-fruit-images-videos-cloud-synced-folder-register-data.gif)

3. Click **Initiate sync**.
   The sync between the folder and your cloud storage begins.

## Resync Data Between Encord and Cloud Storage

As you add or remove data from your cloud storage you need to resync the Cloud-synced folder with your cloud storage to keep it up to date.

There are two ways to resync your data. You can perform a manual refresh OR turn ON the auto refresh feature.

Both manual and automatic resyncing of your data to your Cloud-synced folder scans your bucket for any changes. New files in your cloud storage import to your Cloud-synced folder. Deleted files in your cloud storage are soft deleted in your Cloud-synced folder.

<Note>
  *Soft deleted* means that the data is not removed physically but is no longer visible to users. Soft deleted data is still available in any Projects where the data resides. Labels can be exported from soft deleted data.
</Note>

You can monitor the status and progress of resyncs from the **Activity** tab for the Folder.

### Automatic Refresh

Automatic refreshes occur once every 24 hours.

Manual refreshes do not impact the schedule for automatic refreshes.

You can turn automatic sync ON/OFF when creating a Cloud-synced folder or from the **Details** tab for the folder.

![Folder Info](https://storage.googleapis.com/docs-media.encord.com/static/img/folder-info.png)

![Auto sync Folder Details](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/index-auto-sync.png)

### Manual Refresh

1. Go to **Data** > **Explore**.
2. Click the info bubble on the Cloud-synced folder you want to resync.
3. Click **Resync**.
   The resync between the folder and your cloud storage begins.

![Folder Info](https://storage.googleapis.com/docs-media.encord.com/static/img/folder-info.png)

## Using Cloud-Synced Folders in Projects

When you add a cloud-synced folder to a Project, you can configure Continuous Data Flow (CDF) directly within the Project Data Management modal. Enabling CDF causes new files added to the folder in your cloud storage to automatically appear in the Project after each sync.

<Note>
  The **Continuous Data Flow** toggle is unavailable when you select only a subset of items from a folder. To enable CDF, select all items in the folder.
</Note>

## Import Metadata & Labels

* Learn how to import custom metadata from your cloud storage [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata-ui).

* Learn how to import labels for curation from your cloud storage [here](/platform-documentation/Curate/import-labels-cloud).


# Local Data
Source: https://docs.encord.com/platform-documentation/Curate/add-files/index-upload-local-data



## Upload Local Data

<Note>
  You can upload up to 250 local files at a time.
</Note>

<Info>
  Any files you upload to Encord must be stored in folders. [Click here](/platform-documentation/Curate/index-files#create-a-folder) to learn how to create a folder to store your files.
</Info>

1. Navigate to **Data** > **Files & Folders**.
2. Click the **+ Upload files** button.

<Tip>You can also right-click a folder to add data.</Tip>

<div>
  <img />
</div>

upload-files-new

3. Select a folder to upload your files to. You can click **+New folder** to create a new folder.
4. Select the type of data you want to add.

<div>
  <img />
</div>

* **A** - *Upload* : Drag and drop local text, PDF, video, or image files. Click **Upload** to finish.
* **B** - *Batch images as* : Create an image group or image sequence from local images. See our section on [creating image groups and image sequences](/platform-documentation/Curate/index-files#create-image-groups-and-image-sequences) for more information. Click **Upload and batch images** to finish.
* **C** - *DICOM / NIfTI* : Create a DICOM series from local DICOM files, or upload NIfTI files. Click **Upload** to finish.
* **D** - *Import from private cloud* : Add any data stored in your cloud storage. At least one [data integration](/platform-documentation/General/annotate-data-integrations) is required to register cloud data. Learn how to upload private cloud data [here](/platform-documentation/Curate/add-files/index-register-cloud-data).

<Note>
  To import DICOM files, Encord requires the files to have the following [DICOM tags](https://www.dicomlibrary.com/dicom/dicom-tags/):

  Rows
  Columns
  StudyInstanceUID
  SeriesInstanceUID
  SOPInstanceUID
  PatientID
  The following DICOM tags are required to render DICOM images in 3D:

  ImagePositionPatient
  ImageOrientationPatient
  SliceThickness
  PixelSpacing
</Note>

## Custom metadata

<Note>
  Custom metadata for files uploaded locally can only be [added through the Encord SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).
</Note>

Custom metadata, also known as client metadata, is supplementary information you can add to all data imported into, or registered with Encord. It is provided in the form of a Python dictionary, as shown in examples. Client metadata serves several key functions:

* Filtering and sorting in Index and Active.
* Creating [custom Label Editor layouts](/platform-documentation/Annotate/annotate-label-editor#editor-layout) based on metadata.

You can optionally add some custom metadata per data item in the `clientMetadata` field (examples show how this is done) of your JSON file.

<Info>
  We enforce a 10MB limit on the custom metadata for each data item. Internally, we store custom metadata as a PostgreSQL `jsonb` type. Read the [relevant PostgreSQL documentation](https://www.postgresql.org/docs/9.5/datatype-json.html) about the `jsonb` type and its behaviors. For example, `jsonb` type does not preserve key order or duplicate keys.
</Info>

### Metadata schema

<Note>
  Metadata schemas, including custom embeddings, can only be imported through the Encord SDK.
</Note>

Based on your Data Discoverability Strategy, you need to create a metadata schema. The schema provides a method of organization for your custom metadata. Encord supports:

* Scalars: Methods for filtering.
* Enums: Methods with options for filtering.
* Embeddings: Method for embedding plot visualization, similarity search, and natural language search.

<Tip>Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and the following blank spaces ( ), hyphens (-), underscores (\_), and periods (.).</Tip>

### Metadata schema table

<Tip>Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and blank spaces ( ), hyphens (-), underscores (\_), and periods (.). Metadata schema keys are case sensitive.</Tip>

Use `add_scalar` to add a scalar key to your metadata schema.

| Scalar Key | Description                                                                                                                                                                                | Display Benefits                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| boolean    | Binary data type with values "true" or "false".                                                                                                                                            | Filtering by binary values                        |
| datetime   | ISO 8601 formatted date and time.                                                                                                                                                          | Filtering by time and date                        |
| number     | Numeric data type supporting float values.                                                                                                                                                 | Filtering by numeric values                       |
| uuid       | UUIDv4 formatted unique identifier for a data unit.                                                                                                                                        | Filtering by customer specified unique identifier |
| varchar    | Textual data type. Formally `string`. `string` can be used as an alias for `varchar`, but we STRONGLY RECOMMEND that you use `varchar`.                                                    | Filtering by string.                              |
| text       | Text data with unlimited length (example: transcripts for audio). Formally `long_string`. `long_string` can be used as an alias for `text`, but we STRONGLY RECOMMEND that you use `text`. | Storing and filtering large amounts of text.      |

Use `add_enum` and `add_enum_options` to add an enum and enum options to your metadata schema.

| Key  | Description                                    | Display Benefits                                      |
| ---- | ---------------------------------------------- | ----------------------------------------------------- |
| enum | Enumerated type with predefined set of values. | Facilitates categorical filtering and data validation |

Use `add_embedding` to add an embedding to your metadata schema.

| Key       | Description                                | Display Benefits                                                                        |
| --------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
| embedding | 1 to 4096 for Index. 1 to 2000 for Active. | Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon) |

Use `add_geospatial` to add a new geospatial type to the metadata schema.

| Key        | Description                                                                                                                                                                        | Display Benefits                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| geospatial | Geospatial data that contains latitude and longitude information. Latitude values are between +90 (North) to -90 (South). Longitude values are between +180 (West) to -180 (East). | Filtering data by using a geospatial map. |

<Note>
  * Geospatial custom metadata is supported only in Index.

  * Geospatial custom metadata can be applied to all data unit types and on individual frames in videos.
</Note>

<Warning>
  Incorrectly specifying a data type in the schema can cause errors when filtering your data in Index or Active. If you encounter errors while filtering, verify your schema is correct. If your schema has errors, correct the errors, re-import the schema, and then re-sync your Active Project.
</Warning>

### Import your metadata schema to Encord

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("metadata_1", data_type="boolean")
  metadata_schema.add_scalar("metadata_2", data_type="datetime")
  metadata_schema.add_scalar("metadata_3", data_type="number")
  metadata_schema.add_scalar("metadata_4", data_type="uuid")
  metadata_schema.add_scalar("metadata_5", data_type="varchar")
  metadata_schema.add_scalar("metadata_6", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("my-enum", values=["enum-value-01", "enum-value-02", "enum-value-03"])

  # Add embedding fields
  metadata_schema.add_embedding("my-test-active-embedding", size=512)
  metadata_schema.add_embedding("my-test-index-embedding", size=<values-from-1-to-4096>)

  # Add geospatial
  metadata_schema.add_geospatial("geo-point")

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("G2G", data_type="boolean")
  metadata_schema.add_scalar("Date", data_type="datetime")
  metadata_schema.add_scalar("Cost", data_type="number")
  metadata_schema.add_scalar("Priority", data_type="number")
  metadata_schema.add_scalar("ID-Sys-01", data_type="uuid")
  metadata_schema.add_scalar("ID-Sys-02", data_type="uuid")
  metadata_schema.add_scalar("Description", data_type="varchar")
  metadata_schema.add_scalar("Location", data_type="varchar")
  metadata_schema.add_scalar("Address", data_type="varchar")
  metadata_schema.add_scalar("Translation en-gb", data_type="text")
  metadata_schema.add_scalar("Translation en-ca", data_type="text")
  metadata_schema.add_scalar("Translation en-us", data_type="text")
  metadata_schema.add_scalar("Translation zh-tw", data_type="text")
  metadata_schema.add_scalar("Translation zh-hk", data_type="text")
  metadata_schema.add_scalar("Translation zh-cn", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("ready", values=["ripe", "partially-ripe", "unripe"])
  metadata_schema.add_enum("Fruit", values=["Blueberries", "Cherries", "Apples", "Kiwi"])

  # Add embedding fields
  metadata_schema.add_embedding("active-embedding-01", size=512)
  metadata_schema.add_embedding("active-embedding-02", size=512)
  metadata_schema.add_embedding("index-embedding-100", size=100)
  metadata_schema.add_embedding("index-embedding-1000", size=1000)

  # Add geospatial
  metadata_schema.add_geospatial("Coordinates")

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

### Verify your schema

After importing your schema to Encord we recommend that you verify that the import is successful. Run the following code to verify your metadata schema imported and that the schema is correct.

<CodeGroup>
  ```python Verify schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Verify your schema example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>


# Scene Concepts
Source: https://docs.encord.com/platform-documentation/Curate/add-files/scene-concepts



Scenes are built from timestamped streams. Most teams should register Scenes with the [Scene SDK workflow](/sdk-documentation/index-sdk/sdk-scenes) and [SceneBuilder reference](/sdk-documentation/sdk-references/beta.scene.builder), then use this page when they need to understand how streams, calibration, and raw payloads fit together.

## Sensor Streams and Events

A Scene is built from streams. Point cloud streams, image streams, camera-parameter streams, and frame-of-reference streams each contain timestamped events.

For frame-indexed data, use sequential integer timestamps. For asynchronous sensors, use the original sensor timestamps so Encord can align the latest available event from each stream at the selected time.

## Frame of Reference Hierarchies

Frames of reference describe how the world, ego vehicle, robot, and sensors relate to each other. A typical hierarchy is:

* A root or world frame.
* An `ego` frame for the moving platform.
* Sensor streams linked to `ego`, with static sensor mount poses when the sensor is fixed on the platform.

Use dynamic FoR events when the platform moves over time. Use a static `pose=` on a sensor stream for calibration offsets that do not change.

## Camera Calibration

Camera projection needs both:

* Intrinsics: focal length, principal point, and optional distortion model.
* Extrinsics: the camera pose relative to the Scene frame hierarchy.

Image streams reference camera-parameter streams. If you use `add_image_stream` with inline camera parameters, the SDK creates the camera stream for you.

## Storage Architecture

Composite Scenes reference external point cloud and image files by URI. Container-style data, such as MCAP or ROS bag exports, can contain multiple sensor streams in one file, but the same concepts still apply: streams, events, timestamps, calibration, and frames of reference.

## Camera Distortion Models

The SDK source of truth for supported camera distortion models is [`encord.beta.scene.intrinsics`](/sdk-documentation/sdk-references/beta.scene.intrinsics). The generated table below is produced from that SDK support list.

| SDK API                                    | Model type            | Distortion coefficients                        | Use when                                                                   |
| ------------------------------------------ | --------------------- | ---------------------------------------------- | -------------------------------------------------------------------------- |
| `intrinsics_pinhole(...)`                  | `pinhole`             | None                                           | Use for calibrated pinhole cameras with no distortion.                     |
| `intrinsics_radial(...)`                   | `radial`              | `k1`, `k2`, `k3`                               | Use when calibration only supplies radial coefficients.                    |
| `intrinsics_plumb_bob(...)`                | `plumb_bob`           | `k1`, `k2`, `k3`, `t1`, `t2`                   | Use for Brown-Conrady calibration with radial and tangential coefficients. |
| `intrinsics_fisheye(...)`                  | `fisheye`             | `k1`, `k2`, `k3`, `k4`                         | Use for fisheye lenses calibrated with four coefficients.                  |
| `intrinsics_rational_polynomial(...)`      | `rational_polynomial` | `k1`, `k2`, `k3`, `k4`, `k5`, `k6`, `t1`, `t2` | Use for OpenCV rational-polynomial calibration.                            |
| `intrinsics_simple(..., model="division")` | `division`            | `k`                                            | Use for one-parameter division-model calibration.                          |
| `intrinsics_simple(..., model="ucm")`      | `ucm`                 | `xi`, `k1`, `k2`, `k3`                         | Use for unified camera model calibration.                                  |
| `intrinsics_cylindrical(...)`              | `cylindrical`         | None                                           | Use for cylindrical camera projections.                                    |

## Encord Format Specification

<Important>
  Use the [Scene SDK workflow](/sdk-documentation/index-sdk/sdk-scenes) and [SceneBuilder reference](/sdk-documentation/sdk-references/beta.scene.builder) instead of writing raw upload payloads. The raw Encord format is only for systems that already emit Encord-compatible Scene JSON.
</Important>

<Tabs>
  <Tab title="Basic Example">
    This payload registers one Scene with one point cloud stream.

    ```json Basic theme={"dark"}
    {
      "scenes": [
        {
          "title": "single-pcd-basic",
          "scene": {
            "lidar": {
              "type": "point_cloud",
              "events": [
                { "uri": "s3://my-bucket/scenes/scene-001/lidar/000000.pcd" }
              ]
            }
          }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Advanced">
    This example registers one LiDAR point cloud stream and one image stream with multiple synchronized frames.

    [Download the advanced Scene JSON example](https://storage.googleapis.com/docs-media.encord.com/scene-mid-level-complexity.json).
  </Tab>
</Tabs>


# Collections
Source: https://docs.encord.com/platform-documentation/Curate/collections/index-collections



Collections are saved groups of data units or labels that let you curate subsets of your data and perform bulk actions on them. Rather than repeatedly re-applying the same filters, you save the results as a Collection and act on it directly — whether that means sending items to annotation, running bulk classifications, or exporting a curated dataset.

Collections are available in two places in Encord:

* **Data > Explore** — for organizing files in the Index
* **Project > Explore** — for organizing data units and labels within a project

## Collection types

The collection types available depend on where you are working:

| Context           | Collection type | Used for                                                                                         |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| Data > Explore    | **File**        | Grouping files in the Index for export or dataset creation                                       |
| Project > Explore | **Data**        | Bulk workflow actions on tasks and frames (re-open, prioritize, bulk classify, model evaluation) |
| Project > Explore | **Label**       | Bulk label actions (edit object class, delete labels)                                            |

## Create a collection

The creation flow is the same in both Data > Explore and Project > Explore.

1. Go to **Data > Explore** or open a project and navigate to the **Explore** tab.

2. Search, sort, and filter your data until you have the subset you want to save.

3. Select one or more data units by clicking the checkbox on each data card. To select everything matching your current filters, click **Select all** in the action ribbon at the bottom of the screen.

4. Click **Actions** or press <kbd>A</kbd>.

5. Select **Add to collection**.

6. Click the **+ New Collection** tab.

7. Enter a **Collection Title** (required) and an optional **Collection Description**.

8. If working in a project, select the **Collection Type**:
   * **Data** — for bulk workflow and task actions on frames.
   * **Label** — for bulk label actions (not available in the prediction domain).

9. Click **Create & add** or press <kbd>⌘</kbd><kbd>Enter</kbd> (Mac) / <kbd>Ctrl</kbd><kbd>Enter</kbd> (Windows).

The collection is created and the selected items are added to it. A confirmation notification appears once the operation completes.

<Tip>
  You can also type a name directly in the **Search collections...** field on the **Existing Collection** tab to create a collection inline without switching tabs.
</Tip>

## Add items to an existing collection

1. Select the data units you want to add.

2. Click **Actions** or press <kbd>A</kbd>, then select **Add to collection**.

3. On the **Existing Collection** tab, search for and select the target collection.

4. Click **Add**.

## Remove items from a collection

1. Apply a collection filter so you are viewing items within that collection.

2. Select the items you want to remove.

3. Click **Actions** or press <kbd>A</kbd>, then select **Remove from collection**.

4. Select the collection to remove the items from.

5. Click **Remove**.

## Manage a collection

Once a collection exists, you can access management options from the **Filter** panel. Click the ellipsis icon (**...**) next to a collection name to open the collection actions submenu.

### Collection actions submenu

The submenu header displays the collection name in bold at the top, with the collection's unique ID shown beneath it. Click the copy icon next to the ID to copy it to your clipboard.

<Note>
  The copyable collection ID and grouped actions menu described here apply only to the collection actions submenu in the Explorer filter panel. The collections table row menu is unchanged.
</Note>

Actions in the submenu are organized into sections separated by dividers, making it easier to find the right action. Encord automatically hides sections that have no applicable actions for your current context — for example, workflow actions do not appear outside of a project.

The sections appear in the following order:

* **Navigate** — jump to the collection's filtered view
* **Manage** — rename or update the collection
* **Data** — add to a dataset or download as CSV
* **Workflow** — bulk task and label actions (project context only)
* **Danger** — permanently delete the collection

In **Data > Explore**, configured external action agents appear after the built-in actions. Select an agent to open its trigger dialog.

### Actions available in both Data > Explore and Project > Explore

| Action               | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| **View in Explorer** | Applies the collection as a filter and navigates to the filtered view |
| **Add to Dataset**   | Adds the collection's items to a dataset                              |
| **Edit Details**     | Renames the collection or updates its description                     |
| **Download CSV**     | Downloads the collection contents as a CSV file                       |
| **Delete**           | Permanently deletes the collection                                    |

### Project > Explore only

| Action                 | Description                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- |
| **Task Actions**       | Performs bulk task actions (re-open, prioritize, etc.) — Data collections only  |
| **Bulk Classify**      | Applies a classification to all items in the collection in bulk                 |
| **Convert Collection** | Converts a collection between Data and Label types                              |
| **Edit Object Class**  | Edits label classes across all items in the collection — Label collections only |

## Copy a collection ID

You can copy a collection's unique ID directly from the Explorer filter panel without navigating to the collections table. This is useful for API calls, support requests, or cross-referencing collections.

1. Click **Filter** or press <kbd>F</kbd>.

2. Click the ellipsis icon (**...**) next to the collection.

3. In the submenu header, click the copy icon next to the collection ID.

Encord copies the ID to your clipboard and the copy icon tooltip changes to **Copied** to confirm the action.

## Edit collection details

1. Click **Filter** or press <kbd>F</kbd>.

2. Click the ellipsis icon next to the collection.

3. Select **Edit Details**.

4. Update the **Collection Title** or **Collection Description**.

5. Click **Submit**.

## Export a collection as CSV

1. Click **Filter** or press <kbd>F</kbd>.

2. Click the ellipsis icon next to the collection you want to export.

3. Click **Download CSV**.

<div>
  <img />
</div>

## Delete a collection

<Warning>
  Deleting a collection is permanent. The data units or labels within the collection are not deleted — only the collection grouping itself is removed.
</Warning>

1. Click **Filter** or press <kbd>F</kbd>.

2. Click the ellipsis icon next to the collection.

3. Select **Delete** and confirm.


# Curation Basics
Source: https://docs.encord.com/platform-documentation/Curate/curation-basics



<iframe title="YouTube video player" />

## Filters

You can refine searches by data quality metrics, Collections, custom metadata, folders, data titles, and data types.

<b>Collections:</b> Collections are a way to save interesting groups of data units and labels, to support and guide your downstream workflow.

<b>Custom Metadata:</b> Custom metadata added to data units. The custom metadata added to data units in Folders persists to Annotate Projects and Active.

<Tip>
  For information on importing custom metadata, refer to [Adding Metadata](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata) in the documentation.
</Tip>

<b>Data title:</b> The file name of the image or video.

<b>Data Types:</b> Data, labels, and Predictions can be filtered by: images, image sequences, image groups, and videos.

<b>File ID:</b> The unique hash assigned to the image or video when it imports into Encord.

<b>Folder:</b> The Folder images or videos reside in.

<b>Integration:</b> The integration (if any) your images/videos reside in.

<b>Keyframe:</b> Frames of interest you specified on your videos.

<b>MIME type:</b> Also known as *media type*. The file type of an image or video. For example, `video/mp4`.

<b>Storage location:</b> The location where your images/videos reside. Examples include AWS, GCP, Local.

<b>Uploaded at:</b> The date and time that the image/video uploaded.

**To filter data:**

1. Navigate to **Data** > **Explore** and select a folder.

2. Click the **Filter** dropdown or press <kbd>F</kbd>.

   ![Index Filtering](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-filter.gif)

3. Add and configure the filters you need.

4. Click **Search** to update the results.

### Preset Filters

<Note>
  Presets are only available to customers with the **Curation** package.
</Note>

Preset filters let you save and reuse filtering criteria across your workspace. Since presets are available everywhere during data curation, some may return no results in certain contexts. For example, a preset scoped to Folder A will return nothing when browsing Folder B if Folder A isn't a subfolder of it.

**To create a Preset filter:**

1. Navigate to **Data** > **Explore** and select a folder.

2. Click the **Filter** dropdown or press <kbd>F</kbd>.

3. Add and configure the filters you need.

   ![Index Filtering](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-filter.gif)

4. Click **+Create preset** and give the preset a name.

5. Click **Create** to finish creating the preset.

   ![Create Presets](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-create-filter.gif)

**To use an existing Preset:**

1. Navigate to **Data** > **Explore** and select a folder.

2. Click the **Filter** dropdown or press <kbd>F</kbd>.

3. Select the Preset you want to use from the dropdown. All presets are listed at the top of the list oif filters.

4. Click **Search** to update the results.

<Note>Global filters apply to any Folder, but Local filters only apply on the Folder where the Preset was created.</Note>

### Sorting

Sort your data, in ascending or descending order, using data quality metrics.

**To sort your data:**

1. Navigate to **Data** > **Explore** and select a folder.

2. Select the metric to sort the data.

   ![Index Sort](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-sort.gif)

3. Specify ascending or descending order.

<Tip>
  * Filter and use the natural language searches to further help get the results you want.
  * After filtering, sorting, and searching, create a [Collection](/platform-documentation/Curate/curation-basics#collections).
</Tip>

### Quality Metrics

<Note>
  Quality Metrics are only available to customers with the **Curation** package.
</Note>

<Warning>
  Quality metrics are only calculated when you [upgrade your folder](#folder-upgrade). If you don't see the quality metrics during curation, make sure to upgrade your folder.
</Warning>

Quality metrics evaluate your data, labels, and model predictions, forming the foundation of effective data curation. They provide meaningful ways to surface, rank, and explore your data — helping you identify issues, spot patterns, and make informed decisions about what to curate, fix, or prioritize.

<Note>
  If you add a large amount of new data to a folder, existing uniqueness and diversity scores may no longer reflect the full dataset. You can [recompute these metrics](/platform-documentation/Curate/curation-basics#quality-metrics#recompute-quality-metrics) at any time to bring them up to date.
</Note>

<b>Video Quality Metrics:</b> Video quality metrics must be calculated by upgrading your folder. Examples include Area, Clip duration, Frames per second, Number of frames.

<b>Data Quality Metrics:</b> Data quality metrics must be calculated by upgrading your folder. Examples include Area, Frame number, Random value.

<AccordionGroup>
  <Accordion title="Data Quality Metrics">
    For more detailed information on Data Quality Metrics, refer to the Data Quality Metrics documentation.

    | Title                                                                                                                                           | Metric Type | Ontology Type                                                                                                      |
    | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
    | **Area** - <small>Ranks images by their area (width/height).</small>                                                                            | `image`     |                                                                                                                    |
    | **Aspect Ratio** - <small>Ranks images by their aspect ratio (width/height).</small>                                                            | `image`     |                                                                                                                    |
    | **Blue Value** - <small>Ranks images by how blue the average value of the image is.</small>                                                     | `image`     |                                                                                                                    |
    | **Brightness** - <small>Ranks images by their brightness.</small>                                                                               | `image`     |                                                                                                                    |
    | **Contrast** - <small>Ranks images by their contrast.</small>                                                                                   | `image`     |                                                                                                                    |
    | **Diversity** - <small>Forms clusters based on the Ontology and ranks images from easy samples to annotate to hard samples to annotate.</small> | `image`     |                                                                                                                    |
    | **Frame Number** - <small>Selects images based on a specified range.</small>                                                                    | `image`     |                                                                                                                    |
    | **Green Value** - <small>Ranks images by how green the average value of the image is.</small>                                                   | `image`     |                                                                                                                    |
    | **Height** - <small>Ranks images by the height of the image.</small>                                                                            | `image`     |                                                                                                                    |
    | **Object Count** - <small>Counts number of objects in the image.</small>                                                                        | `image`     | `bounding box`, `checklist`, `point`, `polygon`, `polyline`, `radio`, `rotatable bounding box`, `skeleton`, `text` |
    | **Object Density** - <small>Computes the percentage of image area that is occupied by objects.</small>                                          | `image`     | `bounding box`, `polygon`, `rotatable bounding box`                                                                |
    | **Randomize Images** - <small>Assigns a random value between 0 and 1 to images.</small>                                                         | `image`     |                                                                                                                    |
    | **Red Value** - <small>Ranks images by how red the average value of the image is.</small>                                                       | `image`     |                                                                                                                    |
    | **Sharpness** - <small>Ranks images by their sharpness.</small>                                                                                 | `image`     |                                                                                                                    |
    | **Uniqueness** - <small>Finds duplicate and near-duplicate images.</small>                                                                      | `image`     |                                                                                                                    |
    | **Width** - <small>Ranks images by the width of the image.</small>                                                                              | `image`     |                                                                                                                    |
  </Accordion>

  <Accordion title="Label Quality Metrics">
    Label Quality Metrics are used for sorting data, filtering data, and data analytics.

    | Title                                                                                                              | Metric Type         | Ontology Type                                                                        |
    | ------------------------------------------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------ |
    | **Absolute Area** - <small>Computes object size in amount of pixels.</small>                                       | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Aspect Ratio** - <small>Computes aspect ratios of objects.</small>                                               | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Blue Value** - <small>Ranks annotated objects by how blue the average value of the object is.</small>            | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Border Proximity** - <small>Ranks annotations by how close they are to image borders.</small>                    | `image`             | `bounding box`, `point`, `polygon`, `polyline`, `rotatable bounding box`, `skeleton` |
    | **Brightness** - <small>Ranks annotated objects by their brightness.</small>                                       | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Broken Object Tracks** - <small>Identifies broken object tracks based on object overlaps.</small>                | `sequence`, `video` | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Classification Quality** - <small>Compares image classifications against similar images.</small>                 | `image`             | `radio`                                                                              |
    | **Confidence** - <small>The confidence that an object was annotated correctly.</small>                             | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Contrast** - <small>Ranks annotated objects by their contrast.</small>                                           | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Green Value** - <small>Ranks annotated objects by how green the average value of the object is.</small>          | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Height** - <small>Ranks annotated objects by the height of the object.</small>                                   | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Inconsistent Object Class** - <small>Looks for overlapping objects with different classes across frames.</small> | `sequence`, `video` | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Inconsistent Track ID** - <small>Looks for overlapping objects with different track IDs across frames.</small>   | `sequence`, `video` | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Label Duplicates** - <small>Ranks labels by how likely they are to represent the same object.</small>            | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Missing Objects** - <small>Identifies missing objects based on object overlaps.</small>                          | `sequence`, `video` | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Object Classification Quality** - <small>Compares object annotations against similar image crops.</small>        | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Occlusion Risk** - <small>Tracks objects and detects outliers in videos.</small>                                 | `sequence`, `video` | `bounding box`, `rotatable bounding box`                                             |
    | **Polygon Shape Anomaly** - <small>Calculates potential outliers by polygon shape.</small>                         | `image`             | `polygon`                                                                            |
    | **Randomize Objects** - <small>Assigns a random value between 0 and 1 to objects.</small>                          | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Red Value** - <small>Ranks annotated objects by how red the average value of the object is.</small>              | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Relative Area** - <small>Computes object size as a percentage of total image size.</small>                       | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Sharpness** - <small>Ranks annotated objects by their sharpness.</small>                                         | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Width** - <small>Ranks annotated objects by the width of the object.</small>                                     | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
  </Accordion>

  <Accordion title="Video Quality Metrics">
    | Title                                                                                                                                           | Metric Type | Ontology Type                                                                                                      |
    | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
    | **Area** - <small>Ranks videos by their area (width/height).</small>                                                                            | `video`     |                                                                                                                    |
    | **Aspect Ratio** - <small>Ranks videos by their aspect ratio (width/height).</small>                                                            | `video`     |                                                                                                                    |
    | **Blue Value** - <small>Ranks videos by how blue the average value of the video is.</small>                                                     | `video`     |                                                                                                                    |
    | **Brightness** - <small>Ranks videos by their brightness.</small>                                                                               | `video`     |                                                                                                                    |
    | **Clip Duration** - <small>Ranks videos based on the video's duration.</small>                                                                  | `video`     |                                                                                                                    |
    | **Contrast** - <small>Ranks videos by their contrast.</small>                                                                                   | `video`     |                                                                                                                    |
    | **Diversity** - <small>Forms clusters based on the ontology and ranks videos from easy samples to annotate to hard samples to annotate.</small> | `video`     |                                                                                                                    |
    | **Frame Number** - <small>Selects videos based on a specified range.</small>                                                                    | `video`     |                                                                                                                    |
    | **Frame Label Count**                                                                                                                           | `video`     |                                                                                                                    |
    | **Frames Per Second**                                                                                                                           | `video`     |                                                                                                                    |
    | **Green Value** - <small>Ranks videos by how green the average value of the video is.</small>                                                   | `video`     |                                                                                                                    |
    | **Height** - <small>Ranks videos by the height of the video.</small>                                                                            | `video`     |                                                                                                                    |
    | **Instance Label Count** - <small>Ranks videos by the number of unique objects in the video.</small>                                            | `video`     | `bounding box`, `checklist`, `point`, `polygon`, `polyline`, `radio`, `rotatable bounding box`, `skeleton`, `text` |
    | **Red Value** - <small>Ranks videos by how red the average value of the video is.</small>                                                       | `video`     |                                                                                                                    |
    | **Sharpness** - <small>Ranks videos by their sharpness.</small>                                                                                 | `video`     |                                                                                                                    |
    | **Uniqueness** - <small>Finds duplicate and near-duplicate videos.</small>                                                                      | `video`     |                                                                                                                    |
    | **Unlabelled Frames (%)** - <small>Ranks videos based on the percentage of unlabelled frames in the video.</small>                              | `video`     |                                                                                                                    |
    | **Unlabelled Frames (#)** - <small>Ranks videos based on the number of unlabelled frames in the video.</small>                                  | `video`     |                                                                                                                    |
    | **Width** - <small>Ranks videos by the width of the video.</small>                                                                              | `video`     |                                                                                                                    |
  </Accordion>

  <Accordion title="Model Quality Metrics">
    Model quality metrics help you evaluate your data and labels based on a trained model and imported model predictions.

    **Acquisition Functions**

    Acquisition functions are a special type of model quality metric, primarily used in active learning to score data samples according to how informative they are for the model, enabling smart labeling of unannotated data.

    | Title                                                                               | Metric Type | Data Type |
    | ----------------------------------------------------------------------------------- | ----------- | --------- |
    | **Entropy** - <small>Ranks images by their entropy.</small>                         | `image`     |           |
    | **Least Confidence** - <small>Ranks images by their least confidence score.</small> | `image`     |           |
    | **Margin** - <small>Ranks images by their margin score.</small>                     | `image`     |           |
    | **Variance** - <small>Ranks images by their variance.</small>                       | `image`     |           |
    | **Mean Object Score** - <small>Ranks images by their average object score.</small>  | `image`     | `object`  |
  </Accordion>
</AccordionGroup>

### Natural Language Search

<Warning>
  Natural language search and similarity search can only be performed after you [upgrade your folder](#folder-upgrade).
</Warning>

**To use natural language or image search:**

1. Navigate to **Data** > **Explore** and select a folder.

2. Type a search query or upload an image.

![Natural Language Search](https://storage.googleapis.com/docs-media.encord.com/static/img/natural-lang-search.png)

## Collections

<Note>
  Collections are only available to customers with the **Curation** package.
</Note>

Collections are saved groups of data units or labels that let you curate subsets of your data and perform bulk actions on them, such as sending items to annotation, running bulk classifications, or exporting a curated Dataset.

In the Explorer filter toolbar, each collection has a **...** (three-dot) menu that displays the collection name and its unique collection ID. Click the copy icon next to the ID to copy it to your clipboard — useful for API calls, support requests, or cross-referencing collections. Actions in this menu are organized into logical groups (navigate, manage, data, workflow, and danger) separated by dividers, making it faster to locate the right action. Empty groups are hidden automatically so no stray dividers appear.

## Folder Upgrade

After you data is added into Encord you can upgrade the storage folder that your data resides in. Upgrading your folder calculates quality metrics, generates data embeddings, and enables features like natural language search and embedding plots to support your data curation.

**To upgrade your folder:**

1. Navigate to **Data** > **Files & Folders**.

2. Click into the folder.

3. Click the **info** icon next to the folder name.

4. Click **Folder upgrade**.

<div>
  <img />
</div>

## Delete Files

You can delete files from the Explore Grid View.

<iframe title="YouTube video player" />

**To delete files from the Explore Grid View:**

1. Navigate to **Data**.

2. Click **Explore**.
   The *Explore* page appears displaying files from the currently selected Folder in the Grid view.

3. Change the selected Folder to the Folder with the data units you want to delete.

4. Select one or more data units.

   <Tip>
     Select one data unit and then use `SHIFT` or `CMD`/`CTRL` to select multiple data units.
   </Tip>

5. Click **Actions** > **Delete**.

## Re-index

Re-index forces a full re-indexing of all images, videos, and audio files in Encord.

<Info>Re-indexing helps resolve issues displaying, sorting, or filtering images, videos, frames, or audio files in Encord. It's a troubleshooting tool, not something to use routinely — only re-index if you're actively experiencing one of these issues.</Info>

Encord visualizes the contents of your Folders and sub-folders. As data arrives, it is indexed automatically so content is available almost immediately. Re-indexing clears the existing index and rebuilds it from scratch, ensuring all Folder contents are accurately reflected in Encord.

**When to use Re-index**:

<Info>Please provide a reason why you are re-indexing. The more information you provide, the more prepared we can be with a follow-up.</Info>

Click the **Re-index** button in Encord.

![Re-index](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-reindex.gif)

Re-indexing duration depends on the volume of data and the number of Folders involved. Folders with large amounts of data may take several hours to complete.

<Warning>We strongly recommend against re-indexing while data is actively being imported into the Folder you are viewing in Encord.</Warning>

## Recompute Quality Metrics

<Info>
  Recomputing quality metrics can only be run manually. It is not automatically triggered by adding or removing data from a folder.
</Info>

![Recompute Values](https://storage.googleapis.com/docs-media.encord.com/static/img/recompute-values.png)

You can recompute advanced quality metrics (uniqueness and diversity) for a folder. These scores are calculated relative to the whole dataset, so adding or removing a significant amount of data makes the existing scores stale. Recompute whenever you've made a significant change to a folder's contents and plan to rely on uniqueness or diversity scores, for example before filtering, sorting, or sampling data based on these metrics.

<Note>
  Recomputing only updates uniqueness and diversity scores. Your data, embeddings, and other metrics are untouched.
</Note>


# Custom Embeddings
Source: https://docs.encord.com/platform-documentation/Curate/custom-embeddings



## Default Embeddings

Embeddings are calculated using our purpose-built models, which perform well across a broad range of tasks. For highly specialized domains, custom embeddings may be more appropriate.

Our built-in embeddings power the following features:

* **Natural language search**
* **Image similarity search**
* **Embeddings view**

<Note>Natural language search is also supported with custom embeddings in both **Data** > **Explore** and **Project** > **Explore**. Enabling natural language search for custom embeddings requires additional setup. Contact your Encord representative for help.</Note>

## Custom Embeddings Support

Encord enables the use of custom embeddings for images, image sequences, image groups, and individual video frames. Custom embeddings allow you to incorporate your own feature representations into Encord's platform, enhancing capabilities like similarity search, visualizations, and data filtering. This flexibility supports more advanced workflows and deeper insights tailored to your specific use cases.

## Use Custom Embeddings

To bring your custom embeddings into Encord, you first need to create a key in your metadata schema. After the key is in your schema, you can import your custom embeddings. Custom embeddings can be used for data curation and label validation.

**To use custom embeddings**

1. Create a new `embedding` type in your Schema.
2. Upload your embeddings.
3. Select your custom embeddings from the *Embeddings* view.

<Note>Before you can use embedding plots with your custom embeddings, you need to configure your root Folder in Files.</Note>

### 1. Create New Embedding Type

A key is required in your custom metadata schema for your embeddings. You can use any string as the key for your embeddings. We strongly recommend that you use a string that is meaningful.

If you do not include a key in your metadata schema, your imported embeddings are treated as strings.

<Tip>Embedding key names can contain alphanumeric (a-z, A-Z, 0-1) characters, hyphens, and underscores.</Tip>

Use `add_embedding` to add an embedding to your metadata schema.

<Info>
  We currently support embeddings of:

  * 1 to 4,096 dimensions for data curation.
  * 1 to 2,000 dimensions for label validation.
</Info>

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()


  # Add embedding fields
  metadata_schema.add_embedding('my-test-active-embedding', size=512)
  metadata_schema.add_embedding('my-test-index-embedding', size=<values-from-1-to-4096>)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()


  # Add embedding fields
  metadata_schema.add_embedding('active-embedding-01', size=512)
  metadata_schema.add_embedding('active-embedding-02', size=512)
  metadata_schema.add_embedding('index-embedding-100', size=100)
  metadata_schema.add_embedding('index-embedding-1000', size=1000)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

### 2. Upload Embeddings

With the key in the custom metadata schema ready, we can now import our embeddings.

Custom embedding sizes are flexible and can be set anywhere between 1 and 4096.

You can import embeddings after you have added your data or during your data registration.

<Note>Your key frames (frames specified with or without embeddings) always appear in Encord, regardless of what sampling rate you specify.</Note>

<Tip>Embedding key names can contain alphanumeric (a-z, A-Z, 0-1) characters, hyphens, and underscores.</Tip>

If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

<Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video.</Info>

<AccordionGroup>
  <Accordion title="Import while registering videos">
    #### Import while importing videos

    This JSON file imports embeddings while registering your data with Encord from a cloud integration.

    `config` is optional when importing your custom embeddings:

    ```json theme={"dark"}
    "config": {
        "sampling_rate": "<samples-per-second>",
        "keyframe_mode": "frame" or "seconds",
    },
    ```

    If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

    <Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video.</Info>

    <CodeGroup>
      ```json Import Embeddings Template theme={"dark"}

      {
          "videos": [
              {
                  "objectUrl": "<cloud-file-path-to-your-video-1>",
                  "title": "<title-for-your-video-1>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<samples-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "<cloud-file-path-to-your-video-2>",
                  "title": "<title-for-your-vide-2>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<frames-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "<cloud-path-to-your-video-3>",
                  "title": "<title-for-your-video-3>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<frames-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```

      ```json Example - Simple theme={"dark"}
      {
          "videos": [
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-001.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "111": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "113": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-002.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "157": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "257": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-003.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "11": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "13": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```

      ```json Example - Advanced theme={"dark"}
      {
          "videos": [
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-001.mp4",
                  "title": "awesome-video-001.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "111": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "113": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-002.mp4",
                  "title": "awesome-video-002.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "3",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "157": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "257": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-003.mp4",
                  "title": "awesome-video-003.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "4",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "11": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "13": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update specific videos">
    #### Update specific videos

    <CodeGroup>
      ```python Boilerplate theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

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

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "<data-hash-1>": {
              "$encord": {
                  "frames": {
                      "<frame-number-1>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      },
                      "<frame-number-2>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "<data-hash-2>": {
              "$encord": {
                  "config": {
                      "sampling_rate": <samples-per-second>,  # VIDEO ONLY (optional default = 1 sample/second)
                      "keyframe_mode": "frame" or "seconds",  # VIDEO ONLY (optional default = "frame")
                  },
                  "frames": {
                      "<frame-number-1>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      },
                      "<frame-number-2>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)
      ```

      ```python Example - Simple theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

      # Authentication
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "f2155fa4-6040-408a-84d5-72bacb4f45db": {
              "$encord": {
                  "frames": {
                      "113": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "131": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "f235ad84-f9eb-4dc1-934d-d05e1cd70e59": {
              "$encord": {
                  "frames": {
                      "171": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "231": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)

      ```

      ```python Example - Advanced theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

      # Authentication
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "6b8d797a-4655-43c3-b251-cbd6cc995bc6": {
              "$encord": {
                  "config": {
                      "sampling_rate": 0,  # VIDEO ONLY (optional default = 1 sample/second)
                  },
                  "frames": {
                      "111": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "222": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "d9185f6e-3dbc-443b-bd37-77b2f34f157e": {
              "$encord": {
                  "config": {
                      "sampling_rate": 2,  # VIDEO ONLY (optional default = 1 sample/second)
                      "keyframe_mode": "frame",  # VIDEO ONLY (optional default = "frame")
                  },
                  "frames": {
                      "333": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "444": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Import while registering data units">
    #### Import while importing data units

    This JSON file imports embeddings while registering your data with Encord from a cloud integration.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/data-unit/file-name-01.file-extension",
            "title": "data-unit-title.file-extension",
            "clientMetadata": {"metadata-1": "value", "metadata-2": "value"}
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Example - Simple theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 01",
            "clientMetadata": {
              "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-02.jpg",
            "title": "Blueberry 02",
            "clientMetadata": {
              "embeddings-10": [0.44531257187793305, 0.22303790771089994, 0.1101464760810051, 0.3898273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 03",
            "clientMetadata": {
              "embeddings-10": [0.45631257187793305, 0.23403790771089994, 0.1211464760810051, 0.3678273275803421, 0.06849531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                }
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Example - Advanced theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-01.jpg",
            "title": "Cherry 01",
            "clientMetadata": {
              "Dark": false,
              "Location": "NY",
              "Date": "2024-06-13",
              "ACME Co ID": "8ada6567-c034-4bd4-91d0-04dab5d729d5",
              "Priority": "1",
              "embeddings-10": [
                0.67831257187793305,
                0.32603790771089994,
                0.4341464760810051,
                0.9748273275803421,
                0.23549531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-02.jpg",
            "title": "Cherry 02",
            "clientMetadata": {
              "Dark": false,
              "Location": "NY",
              "Date": "2024-06-13",
              "ACME Co ID": "1262bf57-402e-427c-8c60-276df65513ea",
              "Priority": "1",
              "embeddings-10": [
                0.42531257187793305,
                0.33403790771089994,
                0.5671464760810051,
                0.3688273275803421,
                0.06849531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-03.jpg",
            "title": "Cherry 03",
            "clientMetadata": {
              "Dark": true,
              "Location": "OH",
              "Date": "2024-06-13",
              "ACME Co ID": "3000919f-01e2-4574-a4fd-a2790c4f7b8b",
              "Priority": "2",
              "embeddings-10": [
                0.22231257187793305,
                0.44503790771089994,
                0.7341464760810051,
                0.8368273275803421,
                0.06849531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update specific data units">
    #### Import specific data units

    The custom embeddings format for images, text files, PDFs, and audio files follows the same format as [importing custom metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata#folders-and-custom-metadata).

    ```python theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient
    from encord.http.bundle import Bundle

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

    # Authenticate with Encord using the path to your private key
    user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=SSH_PATH,
    )

    # Define a dictionary with item UUIDs and their respective metadata updates
    updates = {
        "<data-ID-1>": {"<my-embedding>": [1.0, 2.0, 3.0]},
        "<data-ID-2>": {"<my-embedding>": [1.0, 2.0, 3.0]}
    }

    # Use the Bundle context manager
    with Bundle() as bundle:
        # Update the storage items based on the dictionary
        for item_uuid, metadata_update in updates.items():
            item = user_client.get_storage_item(item_uuid=item_uuid)

            # Make a copy of the current metadata and update it with the new metadata
            curr_metadata = item.client_metadata.copy()
            curr_metadata.update(metadata_update)

            # Update the item with the new metadata and bundle
            item.update(client_metadata=curr_metadata, bundle=bundle)

    ```
  </Accordion>
</AccordionGroup>

### 3. Select your Custom Embeddings

<Info>You DO NOT need to re-index your data in Encord for your embeddings to appear. For more information on [re-indexing refer to our documentation](/platform-documentation/Curate/curation-basics#re-index).</Info>

After you import your custom embeddings they are available for:

* Filtering using custom embeddings

* Similarity searches using your custom embeddings

* *Embedding* view and 2D plots with selection based workflows

<Note>Before you can use embedding plots with your custom embeddings, you need to configure your root Folder in Files.</Note>

### Upgrade your Top-Level Folder

Before you can perform filtering, use similarity searches, or use embedding plots with your custom embeddings, you need to configure your top-level Folder in **Data** > **Files & Folders**.

1. Navigate to **Data** > **Files & Folders**.

2. Click into the folder.

3. Click the **info** icon next to the folder name.

4. Click **Folder upgrade**.

<div>
  <img />
</div>

5. Expand the **Custom Embeddings** drop down.

6. Select a custom embedding from the list.

7. Click **Add**.

   The custom embedding appears under *Custom Embeddings*.

   <Note>
     You can add multiple embeddings. Only one embedding can be active in Encord at a time.
   </Note>

8. Expand your selected custom embedding.

9. Select any of the following:
   * Similarity search
   * Compute UMAP Embedding Reduction
   * Compute Advanced Quality Metrics

10. Click **Save and process changes**.

    A dialog appears informing you that the folder upgrade was successful.
    You are now ready to use your custom embeddings.

### Filtering with Custom Embeddings

<Info>
  You must [upgrade your top-level folder](/platform-documentation/Curate/curation-basics#folder-upgrade) to filter using custom embeddings.
</Info>

1. Click the **Filter** dropdown or press <kbd>F</kbd>.

   ![Filter by custom embeddings](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-filter-by-custom-embeddings.gif)

2. Click **Custom Embeddings** from the menu.

3. Select your custom embedding to filter your data.

4. Select **True** to display images, frames, or videos with the custom embeddings.

### Similarity Searches with Custom Embeddings

<Info>
  You must [upgrade your top-level folder](/platform-documentation/Curate/curation-basics#folder-upgrade) before you can use similarity search.
</Info>

1. Click the **Embeddings** icon in the Explorer.

   The Embeddings screen appears.

2. Select the embedding you want to use from the **Select custom embeddings** menu.

   <div>
     <img />
   </div>

3. Click the **Grid** icon.

4. Hover over an image or frame with the custom embedding.

   <div>
     <img />
   </div>

5. Click the **Similarity Search** icon.
   Images and Frames sort according to similarity.

#### Adjust Similarity Search Distance

1. Click the **Embeddings** icon in the Explorer.
   The Embeddings screen appears.

2. Select the embedding you want to use from the **Select custom embeddings** menu.

   <div>
     <img />
   </div>

3. Click the **Grid** icon.

4. Hover over an image or frame with the custom embedding.

   <div>
     <img />
   </div>

5. Click the **Similarity Search** icon.
   Images and Frames sort according to similarity AND a *Distance* filter appears.

   ![Distance filter](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-similarity-search-distance.png)

6. Adjust the **Distance** filter slider to change the similarity search results.

### Embedding View

<Info>
  You must [upgrade your top-level folder](/platform-documentation/Curate/curation-basics#folder-upgrade) before you can view embedding plots.
</Info>

Encord incorporates embedding plots — a two-dimensional visualization technique employed to represent intricate, high-dimensional data in a more comprehensible and visually coherent manner. This technique reduces data dimensionality while preserving the inherent structure and patterns within the original data.

The embedding plot aids in identifying interesting/noteworthy clusters, inspecting outliers, and excluding unwanted samples.

**Use Custom Embedding Plots**

![Vibrant 2D data embedding plot highlighting data patterns and clusters](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-custom-embed-scatter-004.png)

Notice how images are clustered around certain regions. By defining a rectangular area on the plot, users can quickly isolate and analyze data points within that defined region. This approach facilitates the exploration of commonalities among these samples.

Hover over clusters or individual data points on the plot to visually check frames.

Upon selecting a region, the content within the *Explorer* page adjusts accordingly. Various actions can be executed with the chosen group:

* Use [Collections](/platform-documentation/Curate/curation-basics#collections) to tag and group images.
* Establish subsets similar to these and then conduct comparisons.


# Import Custom Metadata (Cloud)
Source: https://docs.encord.com/platform-documentation/Curate/custom-metadata/import-custom-metadata-ui



## READ THIS FIRST

While not required, we strongly recommend importing a metadata schema before importing custom metadata into Encord. The process we recommend:

1. [Import a metadata schema](/platform-documentation/Curate/custom-metadata/index-metadata-schema). If a metadata schema already exists, you can import metadata. You can run a small piece of code to verify that a metadata schema exists
2. Import your custom metadata.

<Note>Performing multiple schema imports overwrites the current schema with the new schema.</Note>

## Import Custom Metadata

You can import custom metadata directly from your cloud storage alongside your data files. When [creating a cloud-synced folder](/platform-documentation/Curate/add-files/index-register-cloud-data-cloud-sync#step-2-create-a-cloud-synced-folder), enable the **Metadata ingestion** toggle and set your sidecar suffix (default is `.metadata.json`). Any file matching that suffix is treated as metadata for its paired data file and does not appear as a separate item in your folder.

<div>
  <img />
</div>

## JSON File

A JSON file is required for each file that you want custom metadata applied on. The JSON file must exist in the same folder as the file.

The JSON's format has the following requirements

* The JSON file must be named as follows: `your-file.extension.metadata.json`.
* A valid JSON object (dict). Not an array or primitive.
* Under 10 MB (or 100 MB if your org has the large metadata files feature).

<Tip>
  Your custom metadata schema determines how custom metadata can be used in the platform. If you do not specify the custom metadata type in the schema the custom metadata imports as `varchar` (a text string).
</Tip>

Here are some examples:

<CodeGroup>
  ```json example-file.file-extension.metadata.json theme={"dark"}

  {
   "metadata-1": "value", 
   "metadata-2": "value",
   "metadata-3": "value", 
   "metadata-4": "value"
  }
  ```

  ```json blueberry_001.jpg.metadata.json theme={"dark"}
  {
    "Fruit": "Blueberry", 
    "Location": "US-NY",
    "Size": "Medium", 
    "Harvested": "2024-09-22", 
    "Organic": "TRUE"
  }
  ```

  ```json lotr-ttt.pdf.metadata.json theme={"dark"}
  {
    "Title": "Lord of the Rings: The Two Towers",
    "Genre": "Fantasy",
    "Author": "J.R.R. Tolkien", 
    "Published": "1954-11-11",
    "Fiction": "TRUE"
  }
  ```
</CodeGroup>


# Metadata Schema
Source: https://docs.encord.com/platform-documentation/Curate/custom-metadata/index-metadata-schema



Before importing your custom metadata, we recommend importing a metadata schema. Schemas help Encord validate your custom metadata and instruct Index and Active how to display it.

<Tip>To manage custom metadata across multiple teams, we recommend using namespaced keys in your schema. This helps avoid conflicts—for example, one team might use `video.description`, while another uses `audio.description` or `TeamName.MetadataKey`. It keeps things organized and clear across departments.</Tip>

### Benefits of Using a Metadata Schema

Using a metadata schema provides several benefits:

* **Validation**: Ensures that all custom metadata conforms to predefined data types, reducing errors during data registration and processing.
* **Consistency**: Maintains uniformity in data types across different datasets and projects, which simplifies data management and analysis.
* **Filtering and Sorting**: Enhances the ability to filter and sort data efficiently in the Encord platform, enabling more accurate and quick data retrieval.

***

### Metadata Schema Table

<Tip>
  * Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and blank spaces ( ), hyphens (-), underscores (\_), and periods (.). Metadata schema keys are case sensitive.

  * If you are unsure about the type to assign to a metadata key, we recommend using `varchar` as a versatile default.
</Tip>

Use [.add\_scalar()](/sdk-documentation/sdk-references/client_metadata_schema#add-scalar) to add a scalar key to your metadata schema.

| Scalar Key | Description                                                                                                                                                                                | Display Benefits                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| boolean    | Binary data type with values "true" or "false".                                                                                                                                            | Filtering by binary values                        |
| datetime   | ISO 8601 formatted date and time.                                                                                                                                                          | Filtering by time and date                        |
| number     | Numeric data type supporting float values.                                                                                                                                                 | Filtering by numeric values                       |
| uuid       | UUIDv4 formatted unique identifier for a data unit.                                                                                                                                        | Filtering by customer specified unique identifier |
| varchar    | Textual data type. Formally `string`. `string` can be used as an alias for `varchar`, but we STRONGLY RECOMMEND that you use `varchar`.                                                    | Filtering by string.                              |
| text       | Text data with unlimited length (example: transcripts for audio). Formally `long_string`. `long_string` can be used as an alias for `text`, but we STRONGLY RECOMMEND that you use `text`. | Storing and filtering large amounts of text.      |

Use `add_enum` and `add_enum_options` to add an enum and enum options to your metadata schema.

| Key  | Description                                    | Display Benefits                                      |
| ---- | ---------------------------------------------- | ----------------------------------------------------- |
| enum | Enumerated type with predefined set of values. | Facilitates categorical filtering and data validation |

Use `add_embedding` to add an embedding to your metadata schema.

| Key       | Description                                | Display Benefits                                                                        |
| --------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
| embedding | 1 to 4096 for Index. 1 to 2000 for Active. | Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon) |

Use `add_geospatial` to add a new geospatial type to the metadata schema.

| Key        | Description                                                                                                                                                                        | Display Benefits                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| geospatial | Geospatial data that contains latitude and longitude information. Latitude values are between +90 (North) to -90 (South). Longitude values are between +180 (West) to -180 (East). | Filtering data by using a geospatial map. |

<Note>
  * Geospatial custom metadata is supported only in Index.

  * Geospatial custom metadata can be applied to all data unit types and on individual frames in videos.
</Note>

<Warning>
  Incorrectly specifying a data type in the schema can cause errors when filtering in Index or Active. To fix this, check your schema, correct any issues, re-import it, and re-sync your Active project.
</Warning>

<AccordionGroup>
  <Accordion title=" Deprecated ">
    While still supported, we STRONGLY RECOMMEND that you use the latest metadata schema instructions.

    | ENUM Name    | String Representation | Description                                                      | Display Benefits                                                                        |
    | ------------ | --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
    | NUMBER       | number                | Numeric data type supporting float values                        | Filtering by numeric values                                                             |
    | STRING       | string                | Textual data type                                                | Filtering by string                                                                     |
    | BOOLEAN      | boolean               | Binary data type with values "true" or "false"                   | Filtering by binary values                                                              |
    | DATETIME     | datetime              | ISO 8601 formatted date and time                                 | Filtering by time and date                                                              |
    | ENUM         | enum                  | Enumerated type with predefined set of values                    | Facilitates categorical filtering and data validation                                   |
    | EMBEDDING    | embedding             | 1 to 4096 for Index. 1 to 2000 for Active.                       | Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon) |
    | LONG\_STRING | long\_string          | Text data with unlimited length (example: transcripts for audio) | Storing and filtering large amounts of text                                             |

    <Warning>
      Incorrectly specifying a data type in the schema can cause errors when filtering your data in Index or Active. If you encounter errors while filtering, [verify your schema](/platform-documentation/Curate/custom-metadata/index-metadata-schema#verify-your-schema) is correct. If your schema has errors, correct the errors, re-import the schema, and then re-sync your Active Project.
    </Warning>
  </Accordion>
</AccordionGroup>

***

### Import Your Metadata Schema to Encord

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("metadata_1", data_type="boolean")
  metadata_schema.add_scalar("metadata_2", data_type="datetime")
  metadata_schema.add_scalar("metadata_3", data_type="number")
  metadata_schema.add_scalar("metadata_4", data_type="uuid")
  metadata_schema.add_scalar("metadata_5", data_type="varchar")
  metadata_schema.add_scalar("metadata_6", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("my-enum", values=["enum-value-01", "enum-value-02", "enum-value-03"])

  # Add embedding fields
  metadata_schema.add_embedding('my-test-active-embedding', size=512)
  metadata_schema.add_embedding('my-test-index-embedding', size=<values-from-1-to-4096>)

  # Add geospatial
  metadata_schema.add_geospatial('geo-point')

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("G2G", data_type="boolean")
  metadata_schema.add_scalar("Date", data_type="datetime")
  metadata_schema.add_scalar("Cost", data_type="number")
  metadata_schema.add_scalar("Priority", data_type="number")
  metadata_schema.add_scalar("ID-Sys-01", data_type="uuid")
  metadata_schema.add_scalar("ID-Sys-02", data_type="uuid")
  metadata_schema.add_scalar("Description", data_type="varchar")
  metadata_schema.add_scalar("Location", data_type="varchar")
  metadata_schema.add_scalar("Address", data_type="varchar")
  metadata_schema.add_scalar("Translation en-gb", data_type="text")
  metadata_schema.add_scalar("Translation en-ca", data_type="text")
  metadata_schema.add_scalar("Translation en-us", data_type="text")
  metadata_schema.add_scalar("Translation zh-tw", data_type="text")
  metadata_schema.add_scalar("Translation zh-hk", data_type="text")
  metadata_schema.add_scalar("Translation zh-cn", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("ready", values=["ripe", "partially-ripe", "unripe"])
  metadata_schema.add_enum("Fruit", values=["Blueberries", "Cherries", "Apples", "Kiwi"])

  # Add embedding fields
  metadata_schema.add_embedding("active-embedding-01", size=512)
  metadata_schema.add_embedding("active-embedding-02", size=512)
  metadata_schema.add_embedding("index-embedding-100", size=100)
  metadata_schema.add_embedding("index-embedding-1000", size=1000)

  # Add geospatial
  metadata_schema.add_geospatial("Coordinates")

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

***

<AccordionGroup>
  <Accordion title=" Deprecated ">
    This is supported, as is, we STRONGLY RECOMMEND that you use the most current method of creating your custom metadata schema.

    <CodeGroup>
      ```python Import schema template theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

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

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH
      )

      user_client.set_client_metadata_schema_from_dict({'metadata_1': 'data type', 'metadata_2': 'data type', 'metadata_3': 'data type'})

      ```

      ```python Example theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

      SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH
      )

      user_client.set_client_metadata_schema_from_dict({'captured_at': 'datetime', 'city': 'datetime', 'dark': 'boolean'})

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

### Verify Your Schema

After importing your schema to Encord we recommend that you verify that the import is successful. Run the following code to verify your metadata schema imported and that the schema is correct.

<CodeGroup>
  ```python Verify schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Verify your schema example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)
  ```
</CodeGroup>

***

<AccordionGroup>
  <Accordion title=" Deprecated ">
    This is supported, as is, we STRONGLY RECOMMEND that you use the most current method of creating your custom metadata schema.

    <CodeGroup>
      ```python Verify your schema template theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

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

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH
      )

      schema = user_client.get_client_metadata_schema()

      print(schema)

      ```

      ```python Verify your schema example theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

      SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH
      )

      schema = user_client.get_client_metadata_schema()

      print(schema)

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## Edit Schema Keys

You can change the data type of schema keys using the [`.set_scalar()`](/sdk-documentation/sdk-references/client_metadata_schema#delete-key) method. The example below shows how to update the data type for multiple metadata fields.

```python Restore Schema Key theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.metadata_schema import MetadataSchema

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get your metadata schema
metadata_schema = user_client.metadata_schema()

# Edit various metadata fields
metadata_schema.set_scalar("metadata_1", data_type="number")
metadata_schema.set_scalar("metadata_2", data_type="boolean")
metadata_schema.set_scalar("metadata_3", data_type="boolean")

# Print the schema for verification
print(metadata_schema)
```

***

## Delete Schema Keys

<Tip> Schema key options cannot be deleted. Instead, we recommend creating new schema key options to meet your needs and phasing out any that are no longer required.</Tip>

You can delete schema keys using the [.delete() method](/sdk-documentation/sdk-references/client_metadata_schema#delete-key).

There are two types of deletion: **hard delete** and **soft delete**. A hard delete permanently removes the key, making it impossible to restore. A soft delete allows you to restore the key later using the [.restore\_key()](/sdk-documentation/sdk-references/client_metadata_schema#restore-key) method.

The following examples show hard delete and soft deletion of a schema key called `Fruit`.

<CodeGroup>
  ```python Soft Delete theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Get your metadata schema
  metadata_schema = user_client.metadata_schema()

  metadata_schema.delete_key(k: "Fruit", hard: False)

  # Print the schema for verification
  print(metadata_schema)
  ```

  ```python Hard Delete theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Get your metadata schema
  metadata_schema = user_client.metadata_schema()

  metadata_schema.delete_key(k: "Fruit", hard: True)

  # Print the schema for verification
  print(metadata_schema)
  ```
</CodeGroup>

### Restore Schema Keys

Keys that have been soft deleted can be restored using the [.restore\_key()](/sdk-documentation/sdk-references/client_metadata_schema#restore-key) method. The following example restores a schema key called `Fruit`.

```python Restore Schema Key theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.metadata_schema import MetadataSchema

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get your metadata schema
metadata_schema = user_client.metadata_schema()

metadata_schema.restore_key(k: "Fruit")

# Print the schema for verification
print(metadata_schema)
```


# Set Up Multimodal Groups
Source: https://docs.encord.com/platform-documentation/Curate/data-groups/index-data-groups



"Data Grouping" (Data Groups) allows you to allocate individual files to groups so that they are more easily annotated and reviewed. This allows you to unlock multi-tile and multi-modal functionality.

Basically, Data Groups are like image groups in Encord, except that Data Groups can include any data type (images, videos, audio files, text files, PDFs) AND that data groups support default and custom layouts for annotation and review.

<Note>
  You can use Data Groups in non-Consensus Projects and Consensus Projects with Review & Refine nodes. Determine Consensus nodes are not yet supported.
</Note>

<Tip>
  For an end-to-end example of how you can use Data Groups, go [here](/end-to-end/Features/e2e-data-groups).
</Tip>

## Data Group Layouts

The order of data units in a Data Group determines how they are arranged in the Label Editor. Encord supports the following:

* Grid (default)
* Carousel
* Custom Layouts

<Tabs>
  <Tab title="Grid Layout">
    ```pgsql theme={"dark"}
    +------------------+------------------------+
    |   data unit 1    |      data unit 2       |
    +------------------+------------------------+
    |   data unit 3    |      data unit 4       |
    +------------------+------------------------+
    ```
  </Tab>

  <Tab title="Carousel Layout">
    In the carousel layout, a scrollable panel on the left shows all data units, while the selected one appears in the main editor view.

    <img />
  </Tab>

  <Tab title="Custom Layout">
    ```pgsql theme={"dark"}
    +-------------------------------------------+
    |              text file                    |
    +------------------+------------------------+
    |   data unit 1    |      data unit 2       |
    +------------------+------------------------+
    |   data unit 3    |      data unit 4       |
    +------------------+------------------------+
    ```
  </Tab>
</Tabs>

## Create Data Groups

<Tip>
  At scale, we recommend [using the SDK to create your Data Groups](/sdk-documentation/index-sdk/sdk-data-groups), specify the layout for your Data Groups, and add Data Groups to Datasets and Projects.
</Tip>

<Info>
  All layouts (grid, carousel, custom) are limited to 50 data units. Attempting to create a data group with more than 50 data units results in an error.
</Info>

### Manually Create Data Groups

<iframe title="YouTube video player" />

1. Go to **Files** > **\[select a Folder]**.
2. Select the files you want to add to a Data Group.
3. Right click your selection.

<div>
  <img />
</div>

4. Hover over **Data group**.
5. Select the [Data Group layout](#data-group-layouts) you want the group to have. The following grid layout options are available:

   * **Row grid layout**: Files are shown side by side in a grid.
   * **Column grid layout**: Files are stacked vertically in a grid.

   <Tip>
     Hover over each Data Group type to see a preview of how the Data Group displays to Annotators and Reviewers.
   </Tip>

<Note>
  * Encord automatically names Data Groups.
  * Data Groups appear in the same folder as its component files.
  * Click the **View details** icon, to see a preview of how the Data Group appears to Annotators and Reviewers.
</Note>

## Auto Data Groups

Auto Data Groups automatically organize files into groups, based on grouping keys you define. Any files sharing the same key are combined into a single data group, so there's no need to manually predefine or maintain groups.

<Note>
  The Auto Data Group feature runs automatically as new data is added to a Cloud-synced Folder. Only new data is grouped. Existing groups remain as they are.
</Note>

<iframe title="YouTube video player" />

**Create Auto Data Groups**:

1. Navigate to **Index** > **Files**.
2. Click **+ New folder**.
3. Select **Auto Data Groups**.

<div>
  <img />
</div>

4. Select a source folder whose files you want to organize into Data Groups. Each folder supports only one grouping configuration. If the selected folder already has one, it is loaded for you to review and edit.

<div>
  <img />
</div>

5. Encord suggests a configuration based on your file naming patterns. You can adjust it by entering:
   * **Grouping keys**: Part of the filename used to identify which files belong together. For example, if you have files named `session-0878-camera-left.mp4` and `session-0878-camera-right.mp4` the grouping key would be `session-0878`.
   * **Group name**: The name of each Data Group. Grouping keys can be referenced as part of the name.
   * **Tiles**: The contents of each tile in the Data Group. Defined using a Regex pattern that matches the filenames you want to include in each tile position. The pattern must include a capture group that matches the grouping key you defined — for example, `(session-\d+)-camera-left\.mp4` where `(session-\d+)` captures the grouping key.
   * **Exclude rules** (optional): Regex patterns to filter out unwanted files, such as excluding any files containing "thumbnail" in the name.
   * **Read-only** (optional): When enabled, annotators cannot add labels to that tile. Enable this for reference or context tiles that should be visible but not annotatable. The **Read-only** toggle appears only after you select a layout type for the group. Encord preserves the read-only setting when you rename a tile, removes it cleanly when you delete a tile, and round-trips it correctly through manifest import and export. AI-suggested configurations also reflect any read-only flags present in the manifest.

<div>
  <img />
</div>

<Note>
  The **Read-only** toggle appears in the tile member editor only after you select a layout type (Grid, List, or Custom) for the group. If no layout type is set, the toggle is not visible. Only dataset managers and admins can configure the read-only setting — annotators cannot change it.
</Note>

6. Optionally, preview the configured grouping by clicking **Run preview**.

<div>
  <img />
</div>

7. Define rules (all rules must be met for a Data Group to be created):
   * **Minimum number of files per Data Group**: The minimum number of tiles that must be matched to create a group. For example, if you define 5 tiles but only 3 matching files are found, you can decide whether the group should still be created.
   * **Required tiles**: Specific tiles that must always be present, regardless of whether the minimum threshold is met. For example, you can mark a particular tile as required, ensuring groups are only created when that tile exists.

<div>
  <img />
</div>

8. Define the Data Group layout. Select one of the following:

   * Grid
   * List
   * Custom

   If you select **Custom**, an **Orientation** dropdown appears with the following options:

   * **Side by side (rows)**: Tiles are placed side by side horizontally, with pairs stacked vertically.
   * **Stacked (columns)**: Tiles are stacked vertically, with pairs arranged side by side.

<Note>
  Selecting a layout type enables the **Read-only** toggle in the tile member editor (step 5). If you need to mark tiles as read-only, set the layout type before configuring individual tiles.
</Note>

<div>
  <img />
</div>

9. Click **Create**.
   A new folder with the same name as your source folder plus the suffix `_grouped` (e.g., `my-folder_grouped`) is created.

### Group Newly Uploaded Files

For a standard (non-cloud-synced) source folder with a saved Auto Data Group configuration, select the root folder and open its **Details** tab. Under **Data Grouping**, click **Run grouping** to group newly uploaded files using the saved configuration.

The **Run grouping** button does not appear for cloud-synced folders, subfolders, or folders without a saved Auto Data Group configuration.

## Label-Branch Overlay for Data Groups

<Note>
  This feature is only available to Workspace and Project Admins, and Team Managers in the REVIEW and COMPLETE Workflow stages.
</Note>

<Tip>
  You can use the [Label Checkpoint Workflow stage](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#branch-overlay-labels) to create a new branch for your labels.
</Tip>

The label-branch overlay button in the annotation editor header is now available when you work with Data Group assets. This lets you visually compare labels from different branches across all tiles in a group simultaneously, making branch-level quality review and comparison workflows possible without manually switching between branches.

**To use the label-branch overlay with a Data Group**:

1. Open a Data Group asset in the annotation editor.
2. Click the **label-branch overlay** button in the editor header.
3. Select the branch you want to overlay.

Encord renders the selected branch's labels in that branch's color on every tile in the group at the same time. This behavior matches the overlay experience already available for single-asset 2D modalities (images, video, DICOM) and 3D scenes.

<Note>
  The label-branch overlay button is only visible when your organization has the branch overlay feature enabled. If you do not see the button in the editor header, contact your Encord administrator.
</Note>

## Share Data Groups with Frame Information

When working with Data Groups that contain video files, you can share links that include specific frame information for each tile. This allows team members to view the exact frames you were working on when you shared the link.

<Note>
  Frame-specific sharing is only available for Data Groups containing video files. For other data types, the standard sharing functionality applies.
</Note>

**To share a Data Group with frame information**:

1. Open the Data Group in the Label Editor.
2. Navigate to the specific frames you want to share across the different tiles.
3. Click the **Share** button in the editor header.
4. Ensure **Include current frame in link** is checked.
5. Click **Copy link**.


# Embedding Plots
Source: https://docs.encord.com/platform-documentation/Curate/embedding-plots



The embedding plot is a 2D visualization of your high-dimensional data, where proximity between points indicates similarity. This makes it easy to spot clusters, outliers, and patterns at a glance.

The Embeddings panel is a toggleable right-hand panel that appears alongside the always-visible grid. When you draw a box selection on the scatter plot, the grid on the left immediately narrows to show only the matching items — no view switching required.

<Info>
  You can draw a rectangular selection on the plot to isolate and explore a specific subset of data points. The grid updates instantly to reflect your selection. Use the *Order by* drop-down to switch the visualization between data and label embeddings.
</Info>

## Prerequisites

* **Data Curation**: To use embedding plots for data curation, you must [upgrade your folder](/platform-documentation/Curate/curation-basics#folder-upgrade) to calculate data embeddings.
* **Label Validation**: To use embedding plots for label validation, you must [calculate metrics and embeddings](/platform-documentation/Validation/label-validation-basics#compute-metrics-and-embeddings).

### Calculate Metrics & Embeddings

<iframe title="YouTube video player" />

1. Navigate to **Projects**.

2. Open the **Explore** tab.

3. Click **Metrics & Embeddings**.

4. Click **Compute** for either option.

5. Specify the following:

   * **Similarity & Natural language search and quality metrics:** Enable to compute embeddings and quality metrics. Access quality metrics for filtering and sorting.
   * **Select embeddings:** Default embeddings are computed by Encord. Alternatively, import and select your own custom embeddings.
   * **Embeddings plot, Diversity and Uniqueness metrics:** Enable to compute UMAP reduction to generate 2D embeddings plots to visualize your data. Also access diversity and uniqueness metrics for curation.

6. Click **Start computation**.

## Using Embedding Plots

<iframe title="YouTube video player" />

1. Navigate to **Data** > **Explore**.

2. Click **Frames** or **Labels**.

3. Click the **Embeddings** icon in the toolbar row to open the Embeddings panel as a right-hand panel alongside the grid.

<Tip>
  * Use the <kbd>V</kbd> + <kbd>E</kbd> shortcut to open the Embeddings panel.
  * You can deep-link directly to the Embeddings panel by appending `?panel=embeddings` to the Data Explorer URL.
  * In addition to selecting points within a rectangular area, you can use filters (but not sort or natural language or image search) on the data or labels.
  * When a natural language or similarity search is active, matching points appear highlighted in color on the scatter plot while non-matching points appear grayed out.
</Tip>

## Selecting Data with the Embeddings Panel

Draw a box on the scatter plot to select a subset of data points. The grid on the left immediately filters to show only the items within your selection. Use the unified selection toolbar at the bottom of the grid to add or remove selected items from a collection.

<Note>
  Hovering over a point on the scatter plot no longer shows an image preview tooltip. The always-visible grid serves this purpose — items matching your selection appear there instantly.
</Note>

To clear a box selection, dismiss the selection filter pill in the toolbar.

**Data Embedding Plot**

<iframe title="YouTube video player" />

**Label Embedding Plot**

<iframe title="YouTube video player" />


# Locating Files
Source: https://docs.encord.com/platform-documentation/Curate/files/data-locating-files-datasets-projects



**To see which Datasets a data unit has been added to**:

1. Navigate to, and select the data unit you want to locate in **Explore**.

<Tip>Use the search bar to search for a specific file.  </Tip>

2. Once the data unit is selected, click the *Linked to* tab on the right of the screen.
   The total number of Datasets the file is linked to, along with their names is shown.

<div>
  <img />
</div>

**To see which Projects a Dataset is attached to**:

3. Click the ellipses icon next to the name of a Dataset.

<div>
  <img />
</div>

4. Select *View dataset*.
   A view of the Dataset appears.

5. Navigate to the *Settings* tab of the Dataset.

6. Select *Linked projects* to see a list of all Projects the Dataset is attached to.

<div>
  <img />
</div>


# Upgrade Mirrored Datasets
Source: https://docs.encord.com/platform-documentation/Curate/files/data-upgrade-mirrored-datasets



<Info>If you are using the SDK, upgrading your Mirrored Dataset can significantly impact your upload process. After upgrading, you must update your SDK scripts to use the `StorageFolder` and `StorageItem` classes for uploading and querying data. For more information, refer to our [documentation](/sdk-documentation/index-sdk/sdk-upload-data).</Info>

<div>
  <img />
</div>

You can easily convert your [Mirrored Datasets](/platform-documentation/Annotate/annotate-datasets/annotate-datasets#mirrored-datasets) into a standard folder and a corresponding Dataset with the same name. Storing your files in a standard folder enables you to add them flexibly to multiple Datasets, and organize them into different folders.

1. Navigate to **Data** > **Datasets** in the Encord platform.

2. Select the Mirrored Dataset you want to upgrade.

3. Click the **Upgrade to standard dataset and folder** button.


# Re-encoding Videos
Source: https://docs.encord.com/platform-documentation/Curate/files/files-re-encoding



<Info>Re-encoding within the Encord platform is only available to Enterprise customers. Contact [sales@encord.com](mailto:sales@encord.com) for more information.</Info>

Encord automatically checks all uploaded videos for re-encoding, a process that ensures they meet our platform's requirements. This prevents [frame synchronization issues](/platform-documentation/General/general-supported-data#frame-synchronization-issues) and guarantees accurate labels.

If a video requires re-encoding, a red badge on the file icon indicates the number of issues. You can view each issue by selecting the file and checking the details pane or by hovering over the badge.

<div>
  <img />
</div>

## How to Re-Encode

<Tip>
  You can Re-encode your videos in the **Files & Folders** or **Datasets** interfaces, but we strongly recommend doing so at the **Files & Folders** level. Videos re-encoded at the Folder level can be used in any Project, while those re-encoded at the Dataset or Project level are restricted to their associated resources.
</Tip>

### Re-encode from Folders

<Info>Re-encoding is only available to Enterprise customers. Contact [sales@encord.com](mailto:sales@encord.com) for more information.</Info>

1. Go to **Data > Sources**.

2. Go into the Folder where the video you want to re-encode resides.

3. Perform one of the following:

* Right-click the video and select **Re-encode** and select the [type of re-encoding](/platform-documentation/Curate/files/files-re-encoding#types-of-re-encoding) to perform.
* Select one or more videos and click **Actions > Re-encode** and select the type of re-encoding to perform.

<div>
  <img />
</div>

4. Check the progress of the re-encoding job by clicking the bell icon in the top-right of the app.

<Info>
  When the process is complete a new video file with the word "normalized" appended to the name appears in the folder. For example, if you re-encoded `snowboard.mp4`, the new video is `snowboard_normalized.mp4`.
</Info>

### Re-encode from Datasets

<Info>Re-encoding is only available to Enterprise customers. Contact [sales@encord.com](mailto:sales@encord.com) for more information.</Info>

1. Go to **Data** > **Datasets**.
   A list of all Datasets available appears on the *Datasets* page.

2. Go into the Dataset where the video you want to re-encode resides.

3. Select one or more videos.

4. Click **Re-encode** and select the [type of re-encoding](/platform-documentation/Curate/files/files-re-encoding#types-of-re-encoding) to perform.

5. Check the progress of the re-encoding job by clicking the bell icon in the top-right of the app. The number displayed in red signifies how many new notifications you have.

When the process is complete a new video file with the word "normalized" appended to the name appears in the folder. For example, if you re-encoded `snowboard.mp4`, the new video is `snowboard_normalized.mp4`.

## Types of Re-encoding

### Automatically fix detected issue

<div>
  <img />
</div>

**Re-encode (Auto)**: Encord performs a spot fix for any detected encoding issues. This is quicker than a full re-encoding, but for some issues, a full re-encoding is required.

### Force full re-encoding

<div>
  <img />
</div>

**Re-encode (Full)**: Encord performs a full re-encoding of the video to a specific frame rate and video codec, regardless of the issues detected. This method ensures all issues are resolved, but it can take significantly more time to perform.

### Re-encode Locally

Some cases, such as corrupted metadata, might require you to re-encode your data locally before uploading them to the Encord platform.

Use the following `ffmpeg` command, replacing `video.mp4` with the name of the file you want to re-encode, and `re-encoded-video.mp4` with the name you want the re-encoded file to have:

```bash theme={"dark"}
ffmpeg -err_detect aggressive -fflags discardcorrupt -i video.mp4 -r 30 -c:v libx264 -movflags faststart -an -tune zerolatency re-encoded-video.mp4
```

<Warning>
  Since browsers require a constant frame rate, we apply the -r 30 flag (30 fps). Verify your video’s frame rate and adjust the value accordingly.
  We recommend using the average frame rate of your video to set the constant rate (rounded to the nearest whole number).

  You can figure out the average frame rate of your video with this command:

  ```bash theme={"dark"}
  ffprobe -v 0 -select_streams v:0 -show_entries stream=r_frame_rate -of default=noprint_wrappers=1:nokey=1 video.mp4 | bc -l
  ```

  You may need to install `ffprobe` & `bc`
</Warning>

<Note>
  Here is a summary of the various flags:

  * `-err_detect aggressive`: Improves error detection during decoding.
  * `-fflags discardcorrupt`: Discards corrupted packets to maintain integrity.
  * `-r 30`: This sets the frame rate to a constant 30 frames per second (FPS). Feel free to adjust `30` to your desired frame rate.
  * `-c:v libx264`: Specifies the `H.264` codec for video re-encoding.
  * `-movflags faststart`: Optimizes for web playback by moving video metadata to the beginning of the file.
  * -an: This ensures the audio is removed from the re-encoded video.
  * `-tune zerolatency`: Configures for low-latency encoding scenarios.
</Note>


# Create Image Groups and Image Sequences
Source: https://docs.encord.com/platform-documentation/Curate/files/index-batch-images



Images can be combined into image groups and image sequences.

1. Navigate to the folder that stores the images you want to combine.

2. Select the images you want to include in the image group or image sequence.

3. Right-click your selection and hover on **Batch images as**.

4. Select **Image group** to create an image group, or **Video (image sequences)** to create image sequences.

<Tip>Image groups can consist of images with different dimensions. In contrast, image sequences are images that all have the same dimensions. When images of varying dimensions are grouped together, multiple image sequences are created, each containing files that share the same dimensions.</Tip>


# Find Duplicate Images
Source: https://docs.encord.com/platform-documentation/Curate/find-duplicate-images



<Warning>
  Duplicate image detection requires an [upgraded folder](/platform-documentation/Curate/curation-basics#folder-upgrade). Ensure your folder has been upgraded before proceeding.
</Warning>

The `Uniqueness` quality metric is used to identify duplicate and near-duplicate images.

<div>
  <iframe />
</div>

## Find Duplicate Images

Navigate to **Data** > **Explore** and select a folder.

Click the **Similarity search** button in the top-right corner of the card. The search results display images with the lowest `Uniqueness` scores, which are the most similar to the selected image.

<Tip>
  Adjust the search distance next to the filter button to find images that are more, or less similar to the selected image.
</Tip>

<div>
  <img />
</div>

## Analytics

Navigate to the **Analytics** view to visualize the distribution of `Uniqueness` scores across the dataset. This can help you understand the extent of duplication in your dataset and make informed decisions about data cleaning.

1. Click the **Analytics** view.
2. Select the `Uniqueness` metric from the dropdown in the **Distribution & Summary Statistics** chart.
   The chart displays the distribution of data based on the `Uniqueness` scores.

![Duplicates Analytics](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-similarity-search-filter.gif)


# Import Labels (Curation)
Source: https://docs.encord.com/platform-documentation/Curate/import-labels-cloud



<iframe title="YouTube video player" />

Label ingestion lets you store annotation data as sidecar files alongside your files in a cloud storage folder. When a folder is configured for label ingestion, Encord automatically detects sidecar files during bucket scans, pairs them with their corresponding data files, and ingests their contents as labels against a chosen Ontology.

## Input Formats

Encord supports two input formats for label ingestion:

* **Encord (JSON sidecars)** — pairs each data file with a JSON sidecar file using a configurable filename suffix.
* **YOLO (.txt sidecars)** — pairs each data file with a YOLO-format `.txt` sidecar file using file path patterns, and maps YOLO class numbers to ontology classes.

<Note>The input format cannot be changed after label ingestion is enabled on a folder.</Note>

<AccordionGroup>
  <Accordion title="Encord (JSON Sidecars)">
    When using the Encord format, configure the **Sidecar suffix** field. Encord pairs each data file with a label file that shares the same name plus the suffix you specify.

    For example, with the default suffix, `image001.jpg` pairs with `image001.jpg.encord.json`.

    The suffix must be between 1 and 128 characters.
  </Accordion>

  <Accordion title="YOLO (.txt Sidecars)">
    [Go here to specify class mapping for the Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#class-mappings)
    When using the YOLO format, configure the following fields:

    * **Image and Label File Patterns**: Use the Image file pattern and Label file pattern fields to define how Encord pairs image files with their corresponding YOLO label files. Both patterns use a shared `{name}` placeholder as the capture group. The value matched by `{name}` in the image pattern must match the value in the label pattern for the two files to be paired. Both patterns must use the same placeholders.

    * **External ID Namespace**: The External ID namespace field determines which namespace Encord reads class numbers from when mapping YOLO class numbers to ontology classes. Encord automatically selects a namespace when you choose an Ontology. It prefers a namespace named `YOLO` (case-insensitive), or falls back to the first available namespace alphabetically. You can unlock the namespace selector to choose a different namespace if needed.

    <Note>If the selected Ontology has no external IDs on its classes, the namespace selector is unavailable and class numbers must be entered manually in the class map.</Note>

    The **Class numbers** editor maps each YOLO class number to an Ontology class. Encord pre-fills class numbers from the external IDs on the selected ontology's classes under the chosen namespace. You can override individual entries by unlocking the relevant row.

    The following Ontology object shapes are supported for YOLO label ingestion:

    * Bounding box
    * Polygon
    * Rotatable bounding box

    <Note>At least one class must be mapped to a YOLO class number. Each YOLO class number can only map to one ontology class. Class numbers must be non-negative integers.</Note>

    If the selected Ontology has no bounding-box, polygon, or rotatable-box objects, Encord displays a warning and you must select a different Ontology.
  </Accordion>
</AccordionGroup>

## How it Works

During each scheduled bucket scan, Encord classifies every file in the folder. Files whose names match the configured suffix are identified as label sidecars and excluded from the data file list. Each sidecar is paired with its corresponding data file, and the label payload is downloaded, validated against the Ontology, and written to the database.

Under the hood, enabling label ingestion provisions labels linked to the Folder and the chosen Ontology.

The ingestion pipeline using a sidecar file:

1. **Labels check**: If an existing sidecar file matches the last ingestion skip (no change).
2. **Download sidecar**: Sidecar files are imported from cloud storage (max 300 MB).

<Note>
  Labels are imported as `ground truth` labels.
</Note>

3. **UUID substitution**: Placeholder UUIDs sent by the SDK are replaced with server-allocated values.
4. **Ontology resolution**: The specified Ontology is loaded and Encord converts the payload into the Ontology's label format.
5. **Label write**:  Labels appear on the data units.

If a sidecar is removed from the bucket, the corresponding label are removed from the data unit.

## Configuration

When creating or editing a Cloud-Synced folder:

1. Toggle **Label ingestion** on.
2. Set the **file suffix** that marks a file as a label sidecar (default: `.labels.json`).
3. Select the *Ontology* to validate and store labels against.

Once saved, subsequent scans begin ingesting labels matching sidecars.

<Warning>
  The Ontology is fixed when you enable label ingestion and cannot be changed. To use a different Ontology, delete the label ingestion configuration and reconfigure the folder. Existing ingested labels are preserved, but new sidecars will ingest under the new Ontology only after reconfiguration.
</Warning>

### Configuration Options

| Option       | Default        | Description                                                                                                                                                                               |
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Input Format | Encord (JSON)  | Choose between **Encord (JSON sidecars)** or **YOLO (.txt sidecars)**. **Cannot be changed after label ingestion is enabled.**                                                            |
| Suffix       | `.labels.json` | (Encord format only) File suffix that identifies a sidecar. Any bucket key ending in this string is treated as a label file; the paired data key is the full key with the suffix removed. |
| Ontology     | (required)     | The Ontology used to validate ingested annotations. **Cannot be changed after label ingestion is enabled.**                                                                               |
| Paused       | `false`        | When paused, sidecars are classified and excluded from data ingestion but are not downloaded or ingested. No new labels are written. Existing labels are preserved.                       |

## File Pairing

Label sidecar files must conform to the Encord label row format. The same schema accepted by the [SDK](/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual).

Maximum sidecar size: **300 MB** (matching the editor HTTP save limit).

Files are paired by stripping the suffix from the sidecar key to derive the data key.

Example with suffix `.labels.json`:

| Data file              | Label sidecar                      |
| ---------------------- | ---------------------------------- |
| `dataset/image001.jpg` | `dataset/image001.jpg.labels.json` |
| `videos/clip_42.mp4`   | `videos/clip_42.mp4.labels.json`   |
| `scans/ct_scan.dcm`    | `scans/ct_scan.dcm.labels.json`    |

## Pausing and Resuming

Pausing stops new sidecars from being downloaded and ingested without removing existing labels. This is the recommended way to temporarily halt label ingestion. For example, while updating your sidecar generation pipeline.

To pause or resume: **Folder details** > **Label ingestion** > **Pause / Resume**.

## Disabling Label Ingestion

Deleting the label ingestion configuration removes the config from the folder. Already-ingested labels are preserved. No new sidecars are picked up after deletion.

To disable: **Folder details > Label ingestion > Delete (trash icon)** > Confirm.

## Supported Data Types

Label sidecars can be paired with any data type supported by cloud-synced folders:

* Images
* Videos
* Audio
* Text
* PDFs
* Time series


# Curate & Explore Audio
Source: https://docs.encord.com/platform-documentation/Curate/index-audio



Encord supports the curation and organization of your audio data in **Data** > **Explore**. You can import your audio data using the UI, from cloud storage (with a JSON file), and using Encord's SDK.

## Data > Explore Audio Support

Data > Explore supports the following audio formats:

| Support     | Description              |
| ----------- | ------------------------ |
| Codec       | .mp3, .wav, .flac, .eac3 |
| Container   | .mp4, .m4a               |
| Sample rate | 8k to 96k                |
| Bit depth   | 16bit to 32bit           |

## Quick Tour

Use the *Audio* tab to natively view all the audio files available in your Folders. From the *Audio* tab you can sort and filter all of your audio files based on [Audio Quality Metrics](#audio-quality-metrics). If only audio files are in your Folders, no *Audio* tab displays. Your audio files display in the Index Explorer. If there are a mix of file types (images, videos, and audio files), tabs display for the various file types (Video, Frames, Audio).

![Quick Overview](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-audio.gif)

* Audio Quality Metrics for sorting and filtering your audio files.

* Waveform playback controls to move through audio files.

## Use Audio Quality Metrics

Use Audio Quality Metrics to sort and filter your audio files.

**Sort**
![Sort with example](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/audio-sort.gif)

**Filter**

![Filter with example](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/audio-filter.gif)

### Audio Quality Metrics

Data > Explore supports filtering your audio files using the following audio quality metrics:

* Bit depth: Size of each sample (int) in bits.
* Duration: The duration of the audio file.
* Number of channels: Number of audio channels in an audio file.
* Random value: A random number assigned to each audio file.
* Samples per second: The number of samples per second.

## Transcription for Audio Files

First update the custom metadata schema to include a `text` (formally `long_string`) data type for your transcripts. Then register data with the appropriately named metadata field. When you display that field, using the *Display* control section of the app, a resizable text field displays, so transcripts can be previewed directly under the relevant audio waveform.

![Transcripts](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/audio-transcripts.gif)

### Step 1: Add Transcript Key to Schema

Before adding transcripts to your audio files, make sure you add a transcript key with `long_string` specified as the type to your custom metadata schema.

```python Add Transcript Key to Schema theme={"dark"}
# Import dependencies
from encord import EncordUserClient

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

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Retrieve the current client metadata schema
current_schema = user_client.get_client_metadata_schema()

# Define the new metadata to append
new_metadata = {'<my-transcript>': 'long_string'}

# Update the current schema with the new metadata
updated_schema = {**current_schema, **new_metadata}

# Set the updated client metadata schema
user_client.set_client_metadata_schema_from_dict(updated_schema)

# Optionally, print the updated schema to verify the changes
print(updated_schema)
```

### Step 2: Import Transcript

After updating your custom metadata schema, you can import your transcripts to your audio files.

```python Import your Transcript theme={"dark"}

from encord import EncordUserClient

# Authentication
SSH_PATH = "<file-path-to-ssh-key>"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
)

# Define a dictionary with item UUIDs and their respective metadata updates
updates = {
    "<data-unit-id-1>": {"transcript-latin": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."},
    "<data-unit-id-1>": {"transcript-en-us": "It is important to take care of the patient, to be followed by the patient, but it will happen at such a time that there is a lot of work and pain. For to come to the smallest detail, no one should practice any kind of work unless he derives some benefit from it. Do not be angry with the pain in the reprimand in the pleasure he wants to be a hair from the pain in the hope that there is no breeding. Unless they are blinded by lust, they do not come forth; they are in fault who abandon their duties and soften their hearts, that is, their labors.
"},
    "<data-unit-id-2>": {"transcript-en-gb": "To be, or not to be, that is the question."},
    "<data-unit-id-3>": {"transcript-en-ca": "You won't hear this from any 1935 comic."}
}

# Use the Bundle context manager
with Bundle() as bundle:
    # Update the storage items based on the dictionary
    for item_uuid, metadata_update in updates.items():
        item = user_client.get_storage_item(item_uuid=item_uuid)

        # Make a copy of the current metadata and update it with the new metadata
        curr_metadata = item.client_metadata.copy()
        curr_metadata.update(metadata_update)

        # Update the item with the new metadata and bundle
        item.update(client_metadata=curr_metadata, bundle=bundle)
```

### Step 3: View/Filter in Index

In Index, you can filter and view the transcripts applied to your audio files.

**View with audio files**

To view transcripts:

1. Click **Display**.

2. Click the field under *Card details*.
   A menu appears.

3. Select your transcript under *Custom metadata*.
   Transcripts appear under your audio files.

![Transcripts](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/audio-transcripts.gif)

**Filter using transcripts**

To filter using transcripts:

1. Click **Filter**.

2. Click **Add filter**.
   A menu appears.

3. Select *Custom metadata*.
   A field appears.

![Transcripts](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/audio-transcripts-02.gif)

4. Select your transcripts from the field.

5. Type the text you want to search for.

6. Click **Display**.

7. Click the field under *Card details*.
   A menu appears.

8. Select your transcript under *Custom metadata*.
   Transcripts appear under your audio files with the filtered text highlighted.

## Long Audio Files

When audio files in your cloud storage are longer than an hour, the Label Editor may take extra time to load their waveforms. To significantly reduce load times, you can generate a JSON file containing the waveform data and store it alongside your audio file.

<Warning>
  Locally imported data CANNOT have long audio performance improved using this method. Improving long audio file performance is **ONLY supported for audio files stored in cloud storage and accessed by Encord through cloud storage.**
</Warning>

<Tip>
  We STRONGLY recommend generating a waveform file for any audio files that are an hour or longer in duration.
</Tip>

1. Install [audiowaveform](https://codeberg.org/chrisn/audiowaveform).

2. Use the following command to generate a JSON file of your waveform:

<Note>
  The name of the JSON file must exactly match the name of your audio file. Only the file extensions differ.
</Note>

<CodeGroup>
  ```bash command theme={"dark"}
  audiowaveform -i ./input.mp3 -o ./waveform-output.json
  ```

  ```bash example theme={"dark"}
  audiowaveform -i "/Users/chris/Documents/awesome-audio-file-01.mp3" \
    -o "/Users/chris/Documents/awesome-audio-file-01.json"
  ```
</CodeGroup>

3. Upload the JSON file to the location of your audio file.

<Note>
  The JSON file MUST reside in the same cloud storage location as your audio file.

  For example:

  * Audio File Path in Bucket : "/my-bucket/all-audio/my-favorite-song.mp3"
  * Audio Waveform File Path in Bucket: "/my-bucket/all-audio/my-favorite-song.json"
</Note>

<Tip>
  You can upload the JSON file during audio file import or any time after.
</Tip>


# Analytics Dashboards
Source: https://docs.encord.com/platform-documentation/Curate/index-custom-analytics-dashboard



You can create custom analytics dashboards from the **Analytics View** using **Distribution** and **Correlation** charts. The Analytics View includes a **Slice strip** at the top of the canvas that lets you define named filter sets called slices and compare data distributions across multiple cohorts simultaneously.

<div>
  <img />
</div>

### Cohort Comparison via Slices

Encord lets you define named filter sets called **slices** and compare data distributions across multiple cohorts simultaneously on the same chart. Each slice appears as its own series, enabling side-by-side comparison without manually switching filters.

#### The Slice Strip

A **Slice strip** appears at the top of the Analytics canvas and is the primary control for creating and managing slices. It contains:

* **All data** — an unfiltered baseline chip that is always present. You cannot remove or rename it.
* **Current filters** — a transient chip that appears automatically whenever you have active toolbar filters. It shares the same filter set as the grid view, and has a dashed border to distinguish it from saved slices. Clicking it opens the **Current filters** editor.
* **User-defined slices** — named slices you create by clicking **+ Add slice**.
* **Add new chart** — opens a menu to add a **Distribution** or **Correlation** chart to the canvas. This button replaces the former floating bottom-right button.
* **How it works?** — opens an illustrated modal explaining bucket-width snapping, shared-grid rebinning, and how hiding slices affects charts.

<Note>
  Slices are saved to your browser's local storage, keyed by project. They persist across page reloads but are specific to your browser and are not shared with other collaborators.
</Note>

#### Adding and Managing Slices

<Steps>
  <Step title="Add a slice">
    Click **+ Add slice** in the Slice strip. Encord creates a new empty slice and immediately opens the slice editor popover.
  </Step>

  <Step title="Configure the slice">
    In the slice editor, you can:

    * Rename the slice.
    * Choose a color for the slice's series on charts.
    * Set filters using the filter controls and any saved presets to define the cohort.
    * Click **View in Explorer** to apply the slice's filters as the active filter set and navigate to the grid view.
  </Step>

  <Step title="Save the slice">
    Close the slice editor popover. The slice chip appears in the Slice strip and Encord immediately adds it as a series on all distribution charts.
  </Step>

  <Step title="Edit a slice">
    Click the pencil icon on a slice chip to reopen its editor and change its name, color, or filters.
  </Step>

  <Step title="Hide a slice from charts">
    Click the eye icon on a slice chip to hide that slice. Encord excludes it from chart queries and the comparison footer entirely, not just from the visual display. Click the icon again to restore it.
  </Step>

  <Step title="Remove a slice">
    Click the remove icon on a slice chip to delete it permanently.
  </Step>
</Steps>

#### Multi-Series Distribution Charts

When you have saved slices or an active **Current filters** set, distribution charts render as multi-series grouped bar charts — one bar series per visible slice. The **All data** baseline always appears as a series unless you hide it. A **comparison footer** below each chart mirrors the visible series from the Slice strip with a per-cohort count summary.

Each distribution chart also offers two bucket alignment modes, which you can toggle directly on the chart:

| **Mode**    | **Description**                                                                                                                                    |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Aligned** | Rebins all series onto a shared bucket grid so bars align side by side for direct comparison.                                                      |
| **Native**  | Keeps each series' own backend bucket edges as translucent overlapping bars on a linear axis, preserving each cohort's natural distribution shape. |

#### Empty Analytics Dashboard

When the Analytics canvas has no charts, Encord displays a headline and quick-start cards. Click a card to add a **Distribution** or **Correlation** chart directly to the canvas.

<Warning>
  The following do not support multi-series slice comparison and continue to use a single-series chart:

  * File and frame client metadata distributions (some metadata endpoints)
  * Feature-hash attribute distributions
  * Text-search boolean distributions
  * Prediction mode distributions
  * Correlation charts (scatter plots), which always display data for the current unfiltered view
</Warning>

### Distribution charts

Distribution charts display distributions and summaries of the selected metrics and custom metadata.

Here are some examples:

* Data unit: Frame number, random value, area
* Metadata: Enum with their enum options, numeric, date time, and boolean

<Note>`varchar` (previously `string`), `text` (previously `long_string`), and `uuid` are NOT SUPPORTED for use in Distribution charts.</Note>

When slices are present or active filters exist, Distribution charts render as multi-series grouped bar charts (see **Cohort Comparison via Slices** above for details on slices and bucket alignment modes).

![Add Distribution chart](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-add-distribution-chart.gif)

### Correlation charts

Correlation charts display a scatter plot of two attributes to show correlation within your current filtered view. Correlation charts require numeric data.

<Note>Distribution charts support a number of custom metadata types, however Correlation charts ONLY SUPPORT `numeric` custom metadata.</Note>

<Note>Correlation charts always display data for the current unfiltered view and do not support multi-series slice comparison.</Note>

![Add Correlation chart](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-add-correlation-chart.gif)

### Stat tiles

Stat tiles display a horizontal bar chart with one bar per slice. Each bar's length is proportional to the item count of the largest slice currently in view, so you can compare slice sizes at a glance even when a small slice sits alongside a much larger baseline. The right-hand label shows the item count and the percentage of the baseline count.

Bar order runs from top to bottom: the unfiltered **All data** baseline appears first, followed by any active toolbar filter slice, then your user-defined slices.

<Note>When an embedding-distance filter is active, Stat tiles cannot retrieve a count for the affected slice and displays a dash (`-`) in place of the count.</Note>

Stat tiles defaults to small (S) size on the dashboard canvas. Encord saves your chart configuration across reloads.

### Metadata coverage

Metadata coverage displays one row per metadata key. Each row contains one horizontal bar per slice, showing how many items in that slice have that key populated. All bars share a common scale — the highest single-slice count across all displayed rows — so you can compare coverage both across slices within a row and across rows for the same slice.

Use this chart to identify which metadata fields carry signal (high coverage) and which are sparsely filled across your dataset slices.

**Selection modes**

Metadata coverage offers two ways to choose which keys to display:

* **Auto mode** (default) — Encord automatically shows the top 20 keys by total coverage across all slices.
* **Explicit mode** — You select specific keys using the **Keys** multi-select dropdown. Selecting or removing any key switches the chart into explicit mode.

To remove an individual key from the chart, click the **×** button on that key's row. To return to auto mode, click the **Reset to top N** link in the chart caption.

Metadata coverage supports both file-level and frame-level metadata domains.

<Note>If your project has no client metadata schema, or if the data query fails, Metadata coverage displays clearly labeled example data so the chart remains usable. The chart caption indicates when example data is showing.</Note>

Metadata coverage defaults to medium (M) size on the dashboard canvas. Encord saves your chart configuration — including any explicit key selections — across reloads.

## Project Overview summary cards

The **Overview** tab of a workflow Project displays a set of summary cards that give you an at-a-glance view of Project health and progress.

<Note>All summary cards described below are hidden for labeling-services-only Projects.</Note>

### Stat cards

A row of three compact stat cards appears at the top of the overview:

* **Tasks completed** — shows completed tasks out of the total task count, with a Project status selector in the footer.
* **Time spent** — shows the total time annotators have spent on the Project. When time data is available, a **Show breakdown** link navigates to the **Collaborators** tab in Analytics.
* **Opened issues** — shows the number of currently open (unresolved) issues. When open issues exist, a **Show tasks** link navigates to the Project queue filtered to tasks with unresolved issues.

### Class distribution card

The **Class distribution** card shows a horizontal bar chart of label instances by class. It displays the top 5 and bottom 5 classes by instance count. When more classes exist between those two groups, the card shows a truncation indicator for the hidden middle classes.

* The card subtitle shows the total number of label instances (for example, "1,234 label instances").
* When no label instances exist yet, the card displays "Instance labels by class will appear here."
* When data is available, a **Show analytics** link navigates to the **Labels** tab in Analytics. This link is hidden when the card is empty.

### Top issue tags card

The **Top issue tags** card replaces the previous Issues overview card. It shows up to 10 issue tags ranked by frequency, displayed as amber-colored horizontal bars. The card subtitle shows the total number of issue tags created for the Project.

* An info popover on the card explains what issue tags are and links to documentation.
* A **Show analytics** link navigates to the **Issues** tab in Analytics. This link is hidden when the card is empty.
* When no issue tags have been used yet, the card displays "Most common issue tags will appear here" and a **Setup issue tags** link to issue-tag settings.

<Note>Tag bar counts reflect tag-action totals rather than unique issue counts. The count for untagged issues is a frontend approximation and may under-report — it can show 0 even when untagged issues exist.</Note>

### Custom Analytics Dashboard

<Tip>Before creating a custom analytics dashboard, we recommend having custom metadata available in your data. Custom metadata can make the insights you get from the dashboard much more useful.</Tip>

1. Navigate to **Data** > **Explore** and select a folder.

2. Click **Analytics view**.

3. Specify the display criteria for the **Distribution** and **Correlation** cards that display by default.

4. Click **Add chart** to add additional charts. The menu offers four chart types:

   * **Distribution** — shows distributions and summaries of selected metrics and custom metadata.
   * **Correlation** — shows a scatter plot of two attributes to reveal correlation within your current filtered view.
   * **Stat tiles** — shows a horizontal bar chart with one bar per slice, displaying item counts relative to the largest slice and as a percentage of the baseline.
   * **Metadata coverage** — shows, for each metadata key, how many items in each active slice have that key populated.

5. Specify the display criteria for the added chart.


# Basics
Source: https://docs.encord.com/platform-documentation/Curate/index-files



Data is structured into folders and subfolders. All files must be placed into folders and cannot be added to the top level / root directory.

<Note>
  You can manage your folders directly from the folder navigation dropdown on the **Data** tab. Click the **⋯** menu next to any folder to access options such as viewing folder information and managing access permissions.
</Note>

<div>
  <img />
</div>

***

## Create a Folder

1. Navigate to **Data** > **Files & Folders**
2. Click the **+ New folder** button to create a new folder. Select the type of folder you want to create.

<div>
  <img />
</div>

3. Give the folder a meaningful name and description.

4. Click **Create** to create the folder.
   The folder is listed in **Files & Folders**.

## Continuous Data Flow

When creating a Project, you can enable **Continuous Data Flow** for any folder type. When enabled, new files added to the folder are automatically added to any project that uses the associated Dataset, without requiring manual updates.

The **Continuous Data Flow** toggle appears in the folder settings panel after you select a folder during project creation.

<Info>The **Continuous Data Flow** toggle only appears after a folder has been selected.</Info>

The toggle behaves differently depending on the folder type:

* **Standard (non-cloud-synced) folders** — The toggle is always interactive. Enable or disable it at any time during Project creation.
* **Cloud-synced folders** — The toggle is only active when auto-sync is turned on for that folder. If auto-sync is off, the toggle is grayed out and cannot be enabled until auto-sync is enabled for the folder.

## Add files to a Folder

1. Navigate to **Data** > **Files & Folders**.
2. Click the **+ Upload files** button

<Tip>You can also right-click a folder to add data.</Tip>

<div>
  <img />
</div>

3. Select a folder to upload your files to. You can click **+New folder** to create a new folder.
4. Select the type of data you want to add.

<div>
  <img />
</div>

* **A** - *Upload* : Drag and drop local images and / or videos. Click **Upload** to finish.
* **B** - *Batch images as* : Create an image group or image sequence from local images. See our section on [creating image groups and image sequences](/platform-documentation/Curate/index-files#create-image-groups-and-image-sequences) for more information. Click **Upload and batch images** to finish.
* **C** - *Audio* Drag and drop local audio files. Click **Upload** to finish.
* **D** - *DICOM* : Create a DICOM series from local DICOM files. Click **Upload** to finish.

<Note>
  To import DICOM files, Encord requires the files to have the following [DICOM tags](https://www.dicomlibrary.com/dicom/dicom-tags/):

  Rows
  Columns
  StudyInstanceUID
  SeriesInstanceUID
  SOPInstanceUID
  PatientID
  The following DICOM tags are required to render DICOM images in 3D:

  ImagePositionPatient
  ImageOrientationPatient
  SliceThickness
  PixelSpacing
</Note>

* **E** - *Import from private cloud* : Add any data stored in your cloud storage. At least one [data integration](/platform-documentation/General/annotate-data-integrations) is required to register cloud data. Learn how to upload private cloud data [here](/platform-documentation/Curate/add-files/index-register-cloud-data). Click **Import** to finish.

### Create Image Groups and Image Sequences

Image groups and image sequences are created when you upload files into Encord.

1. Open the *Add data* dialog.
2. Select the *Batch images as* tab.
3. Select *Image group* to create an image group. Select *Image sequence* to create an image sequence.

<div>
  <img />
</div>

4. Drag-and-drop the local images you want to batch into an image group or image sequence.

5. Click **Upload and batch images** to create the image group or image sequence.

6. A file representing the image group or image sequence is created in the folder. A new folder appears containing all the constituent images of the image group or image sequence that was created.

<div>
  <img />
</div>

<Note>
  * The new folder containing the constituent images is not synced.
  * Adding new images to this folder does not add them to the image group or image sequence.
  * Files contained in the image group or image sequence cannot be deleted from the folder until the image group or image sequence is deleted.
</Note>

### Register Cloud Data

<Tip>We recommend uploading files in batches not exceeding 2GB, to ensure upload does not exceed 3 hours.</Tip>

To add data from your private cloud you need the following:

* A [private cloud integration](/platform-documentation/General/annotate-data-integrations).

* A [JSON or CSV file specifying the data](/platform-documentation/Curate/add-files/index-register-cloud-data#specify-cloud-data) you want to add from your private cloud.

See our documentation on [data integrations](/platform-documentation/General/annotate-data-integrations), and [adding cloud data](/platform-documentation/Curate/add-files/index-register-cloud-data) for comprehensive guides.

***

## Perform Actions on Selected Files

When you select files in **Data** > **Files & Folders** or **Data** > **Explore**, you can perform various actions on them using the **Actions** button that appears in the toolbar.

1. Select the files you want to perform actions on by clicking on them.

<Tip>To select multiple files, hold the <kbd>Shift</kbd> key and click to select a range, or hold <kbd>Ctrl</kbd> (or <kbd>Cmd</kbd> on Mac) to select individual files.</Tip>

2. Click the **Actions** button in the toolbar, or press <kbd>A</kbd> on your keyboard.

3. Choose from the available actions:
   * [**Add to dataset**](#add-data-to-datasets) — Add the selected files to an existing dataset or create a new dataset
   * [**Add to collection**](/platform-documentation/Curate/curation-basics#collections) — Add the selected files to a collection for organization
   * **Remove from collection** — Remove the selected files from their current collection

### Add data to Datasets

After data is uploaded to Encord it can be added to one or multiple Datasets.

1. Select the data you want to add to a Dataset.

<Tip>To add multiple files to a Dataset, bulk-select files by selecting the first file, and then selecting the last file while holding the <kbd>Shift</kbd> key on your keyboard.</Tip>

2. Click the **Actions** button and select **Add to dataset**, or right-click your selection and select **Add to dataset**.
   A dialog appears.

<div>
  <img />
</div>

3. You have the option to:

* Add data to an existing Dataset by clicking **Add** next to the Dataset's name on the *Existing datasets* tab. You can add data to multiple Datasets.

<div>
  <img />
</div>

* Create a new Dataset to add your data. Select the *+New dataset* tab and give the Dataset a meaningful name and description. Click **Add to new dataset** to add the files to the new Dataset.

<div>
  <img />
</div>

***

## View, Search, and Manage your Files

Files allows you to search for data units, and view which Datasets each data unit is belongs to.

The global search bar searches all data in Files, irrespective of which folder is currently open.

<div>
  <img />
</div>

Click a data unit to see file specific details. Navigate to the *Linked to* tab to see which Datasets this file is added to. Click the details icon next to the Dataset to:

* View the Dataset.
* Remove the selected file from Datasets.

<div>
  <img />
</div>

### Organize Folders with Tags

Folder tags use the tags defined for your Workspace. Users with Admin access to a folder can add or remove its tags from the **Tags** column or the **Tags** section in the folder details panel. Other users can view assigned tags.

To filter folders, click the filter button beside the search box and select **Tags**. When you select multiple tags, Encord shows folders that have all the selected tags. Tag filtering searches folders recursively within the open folder; from the root, it searches all folders.

### Delete and Move Files and Folders

Right-click a file, folder, or a selection of multiple files to see the options available to you.

<div>
  <img />
</div>

* To delete files and folders, right-click the selection and select **Delete**.

<Warning>Deleting a file removes it from all Datasets it was added to. </Warning>

* To move files and folders to a different folder, right-click the selection and select **Move to another folder**. A dialog appears. Start typing the name of the folder, select the folder you want to move the selection to, and click **Move** to confirm.

<div>
  <img />
</div>

### Folder Permissions and Activity

Folder details are automatically displayed whenever a folder is:

* Selected
* Open and no data unit is selected

<div>
  <img />
</div>

### Manage Folder Collaborators

<Note>Workspace admins can see all the files and folders created by users in your Workspace. </Note>

Click **Manage access** to manage which users within your [Workspace](/platform-documentation/General/general-workspace-settings) can access the folder. A dialog appears with the *Invite* tab open by default.

<div>
  <img />
</div>

Select the role you want the users to have, and then start typing their email address into the search bar. Select the user(s) you want to give access to the folder and click **Add** to confirm your selection.

<div>
  <img />
</div>

To delete a user from a folder, navigate to the *Manage* tab and click the *Delete* button.

Change a user's access permissions by selecting a new role from the dropdown.

<Note>Users with *Admin* permissions cannot be deleted, and their role cannot be changed. </Note>

### See All Files in Your Workspace

Workspace admins can access all files stored in their Workspace.

1. Navigate to **Data** > **Explore** in the Encord platform.
2. Click **\[Workspace name] folders**.

<div>
  <img />
</div>


# Curate Geospatial Data
Source: https://docs.encord.com/platform-documentation/Curate/index-map-view



Encord supports curation of data with geographical custom metadata. You can filter data by geographical custom metadata, but Encord provides a *Map View* to select/filter data using geo-borders.

## STEP 1: Apply Geospatial Custom Metadata

Before you do anything, you need to apply geospatial custom metadata to your data. To learn how to apply geospatial custom metadata:

1. Create a [Metadata Schema](/sdk-documentation/index-sdk/custom-metadata/sdk-index-metadata-schema)

2. Apply [geospatial custom metadata](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata#geospatial-custom-metadata) on [new data](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata#import-custom-metadata) or [existing data](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata#import-to-files-already-in-index).

## STEP 2: Filter Data

Use the following ways to filter geospatial custom metadata:

* Custom metadata filter
* *Map View*

1. Go to **Data** > **Explore**.

2. Select the folder containing the files.

3. Perform one of the following:

   * Filter the data units using a custom metadata field.
   * Use the *Map View* to select/filter the data units.

<Note>The *Map View* opens as a right-hand panel alongside the always-visible grid. When you draw a shape on the map, Encord applies the geospatial filter, zooms the camera to the selected area, and discards the drawing. The filter pill in the toolbar is the only persistent artifact — dismiss it to clear the filter. The grid on the left updates immediately to show matching items.</Note>

**Custom Metadata Filter**

<video />

**Map View**

<video />

## Map Style Picker

The *Map View* includes a style picker in the bottom-right corner of the map. Use it to switch the map background between three styles:

* **Map** — Standard vector map. Respects your dark or light mode setting.
* **Satellite** — Satellite imagery with street overlays, useful for real-world visual reference.
* **Terrain** — Topographic/outdoors style, useful for understanding elevation and landscape context.

<Note>The **Map** style is the only style that adapts to dark and light mode. **Satellite** and **Terrain** styles always display in their default appearance regardless of your mode setting.</Note>

<Note>Your style selection resets to **Map** each time you reload the page.</Note>

### Switching styles

Switching between styles preserves your current map position — including location, zoom level, bearing, and pitch. Any rectangle selections you have drawn on the map also persist across style switches.

To switch the map style:

1. Open the *Map View* in the Geospatial Explorer.
2. Locate the **Map / Satellite / Terrain** pill control in the bottom-right corner of the map.
3. Click the style you want to apply. The map background updates immediately and your position and any drawn selections are retained.

## Map Interaction Modes

### Opening the Map View

The *Map View* is a toggleable right-hand panel in the Data Explorer. The grid remains visible on the left at all times. Click the **Map** icon in the toolbar row, or press `V` then `M`, to open or close the Map panel. You can also deep-link directly to the Map panel by appending `?panel=map` to the Explorer URL.

## Drawing a Shape and Applying a Geospatial Filter

<Warning>The map draw gesture is ephemeral. Unlike the previous behavior, Encord no longer displays a persistent orange bounding box after you draw a shape. Instead, the drawing is discarded as soon as the filter is applied. Use the filter pill in the toolbar to see and clear the active geospatial filter.</Warning>

<Steps>
  <Step title="Open the Map panel">
    Click the **Map** icon in the toolbar row or press `V` then `M`.
  </Step>

  <Step title="Draw a shape">
    Use the draw tool in the map toolbar to draw a rectangle over the area you want to filter. The map starts in cursor/select mode — switch to the draw tool before drawing.
  </Step>

  <Step title="Review the results">
    Encord applies the geospatial bounding-box filter, zooms the camera to the selected area, and discards the drawing. The grid on the left immediately narrows to show only matching items.
  </Step>

  <Step title="Clear the filter">
    Dismiss the filter pill in the toolbar to remove the geospatial filter and restore the full grid.
  </Step>
</Steps>

## Selecting and Acting on Items

After the grid narrows to your filtered items, use the unified selection toolbar at the bottom of the grid to select items and add or remove them from collections. The per-view selection toolbar that previously appeared in the Map panel no longer exists — all selection actions happen in the grid.

## Map Interaction

The *Map View* provides two interaction modes, selectable from the toolbar that appears below the geocoder search box in the top-left corner of the map. The toolbar is only visible when a geospatial metadata key is configured for your Project.

<Note>Keyboard shortcuts are disabled when a modal is open or when your cursor focus is in the geocoder search box.</Note>

### Pan & Click mode

**Pan & Click** is the default mode when you open the *Map View*. In this mode, you can pan the map, zoom, and click individual data points or clusters. Use the keyboard shortcut `C` to switch to this mode.

### Box Select mode

**Box Select** mode lets you draw a rectangular selection directly on the map by clicking and dragging. Use the keyboard shortcut `B` to switch to this mode.

In Box Select mode:

* The cursor changes to a crosshair.
* Map panning is disabled while you drag.
* A blue bounding-box outline appears on the map as you drag and persists after you release to show the selected area.
* Hover thumbnails and point-click handlers are suppressed while a drag is in progress.
* Press `Escape` to clear the current selection.

### Applying a box selection as a filter

After you complete a box selection, a **Zoom into selection** button (filter icon) appears at the corner of the selection box. Click it to promote the selection to a persistent geospatial filter and zoom the map to fit the selected area.

### Keyboard shortcuts

| Key      | Action                          |
| -------- | ------------------------------- |
| `C`      | Switch to Pan & Click mode      |
| `B`      | Switch to Box Select mode       |
| `Escape` | Clear the current box selection |

## Cluster Click-to-Zoom

The *Map View* displays data points as clusters when many items occupy the same geographic region. Click clusters to progressively drill down into smaller areas until individual items become visible.

### How cluster drill-down works

Clicking a cluster applies a tight geospatial bounding-box filter around that cluster's region and re-queries the server at finer granularity. You can repeat this process — clicking clusters to narrow the view — until the filtered region contains 1,000 or fewer items.

When the filtered region contains 1,000 or fewer items, the map automatically switches from aggregated cluster markers to individual data point markers. Each individual point represents a single data item with its exact coordinates.

<Note>The 1,000-item threshold is a fixed limit. It is not configurable.</Note>

### Clicking individual points

Once the map switches to individual-item mode, click any single point marker to open the **Item Preview Modal** for that data item. The modal displays the item's details directly from the map view.

<Note>While the **Item Preview Modal** is open, the map viewport controls and style picker are hidden. They reappear when you close the modal.</Note>

<Warning>The **Show Similar**, **View Next**, and **View Previous** actions in the Item Preview Modal are not yet functional when you open the modal from the map. These actions are available as expected when you access item previews through other parts of the Explorer.</Warning>

### Summary of click behavior

| What you click                                              | What happens                                                       |
| ----------------------------------------------------------- | ------------------------------------------------------------------ |
| Cluster marker (grouped points)                             | Applies a bounding-box filter and zooms into that cluster's region |
| Aggregate point marker (multiple items at one location)     | Narrows the filter to that location's area                         |
| Individual point marker (single item, ≤1,000 items in view) | Opens the Item Preview Modal for that item                         |


# Curate & Explore Visual Data
Source: https://docs.encord.com/platform-documentation/Curate/index-video



Use the *Video* tab in **Data** > **Explore** to natively view all the videos available in your Folder. From the *Video* tab you can sort and filter all of your videos based on [Video Quality Metrics](/platform-documentation/Curate/curation-basics#quality-metrics). You can also apply video frame level metrics while in the *Video* tab.

<Info>Video frames are sampled for metric and embedding calculation at 1 FPS starting from the first frame. Using [`keyframes` and custom metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata) you can specify the frames you want imported. Contact us to discuss changing the sampling frame rate how to indicate specific frames.</Info>

![Quick Overview](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-video.gif)

1. Video Quality Metrics for sorting and filtering your videos.

2. A compact card grid of all videos in the Folder. Hover over a card to preview the video.

3. Click **+ N frames** on a card to expand that video in place into a full-width frame strip, with frame-level metrics and analytics controls in the row header.

## Browse videos in the card grid

Each unexpanded video appears as a compact card showing a thumbnail, its duration, and its sort metric.

* **Hover to preview**: Hovering over a card automatically plays a muted, looping preview of the video, so you can screen footage without opening it. Labels are not currently overlaid on this preview.
* **Select a video**: Hover over a card to reveal a selection checkbox, along with quick actions such as similarity search.
* **Expand a video**: Click **+ N frames** on a card to expand that video in place into a full-width frame-strip row. The row appears at the video's current sort position, and the other cards flow around it.

<Info>Collections are shown on video cards. Selecting and adding videos to a Collection selects the whole video, not individual frames.</Info>

## Inspect an expanded video

Expanding a video replaces its card with a full-width row showing its sampled frames. The row header consolidates the controls previously spread across the view:

* A frame-metric selector, for sorting or coloring frames by a specific quality metric.
* The **Show only Keyframes** toggle — see [Keyframes](/platform-documentation/Curate/index-keyframes#browse-videos-by-keyframes).
* An **Analytics** button that opens a frame-level analytics chart. This requires the `explore_analytics` feature to be enabled on your organization.
* A **Collapse** (or **Hide frames**) button that folds the video back into the card grid. Collapsing a video also closes its analytics chart.

The frame-offset slider used to move through a video's frames only appears once that video is expanded.

<Tip>To have every video expanded by default instead of browsing the card grid first, enable **Load video frames by default** in the Display panel.</Tip>

## Use Video Quality Metrics

Use Video Quality Metrics to sort and filter your videos. For a full list refer to the [Video Quality Metrics](/platform-documentation/Curate/curation-basics#quality-metrics) page.

![Filter with example](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-video-metrics.gif)

## Display settings for video cards

Click **Display** to configure how video cards appear in the grid:

* **Card details**: Choose the title, Collections, and selected metric shown on each video card, the same **Card details** control used for other data types.
* **Grid density**: The grid-count slider controls the height of an expanded video's frame-strip row. It does not change the width of unexpanded video cards, which stays fixed.


# Modalities in Encord
Source: https://docs.encord.com/platform-documentation/Curate/modalities-landing-page



## Modalities

<CardGroup>
  <Card title="Multimodal" icon="file-lines" href="/platform-documentation/Curate/data-groups/index-data-groups">
    Learn how to use Data > Explore with multimodal data (Data Groups).
  </Card>

  <Card title="3D Scenes" icon="cube" href="/platform-documentation/Curate/add-files/add-pcd-data">
    Learn how to use curation with point clouds, LiDAR, radar, camera images, and calibrated sensor streams.
  </Card>

  <Card title="Videos" icon="video" href="/platform-documentation/Curate/index-video">
    Learn how to use Data > Explore with video.
  </Card>

  <Card title="Time Series" icon="chart-line" href="/platform-documentation/Annotate/annotate-label-editor/annotate-time-series">
    Learn how to annotate time series data.
  </Card>

  <Card title="Audio" icon="file-audio" href="/platform-documentation/Curate/index-audio">
    Learn how to use Data > Explore with Audio.
  </Card>

  <Card title="Documents" icon="file-pdf" href="/platform-documentation/Curate/index-documents">
    Learn how to use Data > Explore with PDF documents.
  </Card>

  <Card title="Text and HTML" icon="file-lines" href="/platform-documentation/Curate/index-text-files">
    Learn how to use Data > Explore with plain text and HTML files.
  </Card>
</CardGroup>


# Manage Integrations
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations



<Info>Only users that are part of a Workspace can create data integrations.</Info>

Navigate to [Workspace Settings](/platform-documentation/General/general-workspace-settings#workspace-settings) > Cloud Buckets to view and manage your cloud storage integrations.

<div>
  <img />
</div>

## Security

<Tip>
  For standard integrations, use a short URL expiry time for the tightest security.
</Tip>

* Encord generates signed URLs dynamically and does not store them. All signed URLs have an expiry time which can be configured by the person who is creating the integration. Encord uses HTTPS/ TLS 1.2 and above to ensure data transport is encrypted.

* Encord uses RBAC which allows only users who have required permissions to access the data. We also have CORS config to provide browser level protection by restricting the domains that can access the signed URLs.

* Encord is SOC 2 compliant.

* For enhanced security, create a [Direct Access integration](/platform-documentation/General/annotate-data-integrations/annotate-direct-access-integration) with *Strict client-only access*. This combination ensures the highest level of data protection: *Strict client-only access* prevents Encord from accessing your data, while Direct Access keeps Encord from signing the URLs, maintaining your data's confidentiality.

## User Roles and Permissions

Integrations have the following user based access controls.

<div>
  | Permission                          | Admin | User |
  | ----------------------------------- | ----- | ---- |
  | View integration                    | ✅     | ✅    |
  | Register data using the integration | ✅     | ❌    |
  | Rename integration                  | ✅     | ❌    |
  | Delete integration                  | ✅     | ❌    |
  | Add users                           | ✅     | ❌    |
</div>

***

## Rename an Integration

Integration admins can rename an integration from its integration card:

1. Click the pencil icon next to the integration title.
2. Enter a new title.
3. Press <kbd>Enter</kbd> or click outside the title field to save your changes. Press <kbd>Esc</kbd> to cancel.

***

## User Management

<Note>The user who creates the cloud integration becomes its administrator and gains immediate access to use it. Only integration admins can add users to an integration. </Note>

Users must be added to a cloud integration before they can use it to register data with Encord.

### Add Users

<div>
  <img />
</div>

**Add individual users to an integration**:

1. Click the **Add or remove users** button on the integration.
   A dialog appears.

2. Ensure the *Invite* tab is selected.

3. Ensure the *Individual* tab is selected

4. Type the email addresses of the users you want to share the integration with and press <kbd>Enter</kbd> on your keyboard to confirm.

5. Select the integration user role you want to assign to the users.

6. Click **Add**.

<div>
  <img />
</div>

**Add user groups to an integration**:

1. Click the **Add or remove users** button on the integration.
   A dialog appears.

2. Ensure the *Invite* tab is selected.

3. Click the *Groups* tab.

4. Select a user group you want to add to the integration

5. Select the integration user role you want to assign to all users in the group.

6. Click **Add**.

<div>
  <img />
</div>

### Remove Users

<Note>
  Individuals with the Admin user role can only be removed from the integration from a Workspace Admin.
</Note>

<div>
  <img />
</div>

**To remove individual users from an integration**:

1. Click the **Add or remove users** button on the integration.
   A dialog appears.

2. Select the *Manage* tab.

3. Ensure the *Individuals* tab is selected.

4. Click the delete icon next to the user you want to remove from the integration.

<div>
  <img />
</div>

**To remove a user group from an integration**:

1. Click the **Add or remove users** button on the integration.
   A dialog appears.

2. Select the *Manage* tab.

3. Select the *Groups* tab.

4. Click the delete icon next to the user group you want to remove from the integration.

<div>
  <img />
</div>

***

## Strict Client-only Access

*Strict client-only access* allows Encord to sign URLs without temporarily processing information on our servers. *Strict client-only access*  is available for all types of private cloud integrations, including [Direct access](/platform-documentation/General/annotate-data-integrations/annotate-direct-access-integration).

There are two main consequences of making an integration client-only access:

1. Specific server-side features (data conversion and cloud-synced folders) **DO NOT** work. This includes features such as:

   * [Cloud-synced Folders](/platform-documentation/Curate/add-files/index-register-cloud-data-cloud-sync)
   * [Image groups](/platform-documentation/General/general-supported-data#image-groups) & [image sequences](/platform-documentation/General/general-supported-data#image-sequences).
   * [Re-encoding videos](/platform-documentation/General/general-supported-data#re-encode-videos).
   * [Segment-anything model (SAM)](/platform-documentation/Annotate/automated-labeling/annotate-sam).

2. Metadata must be specified for all data in the [JSON file when adding data to a dataset](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format). The [metadata section](#metadata) shows how to specify the metadata.

### Enabling Strict Client-Only Access

Strict client-only access is enabled by checking the **Strict client-only access, server-side media features will not be available** checkbox in the *Advanced settings* section when creating an integration.

<div>
  <img />
</div>

A green tick and the words *Client-only access* are visible on all client-only access integrations.

<div>
  <img />
</div>

<AccordionGroup>
  <Accordion title="Metadata">
    ### Metadata

    * Organizations with strict data compliance requirements that prevent Encord from temporarily processing data on our servers.
    * Use cases where customers want to provide their own video metadata to ensure the highest level of accuracy for frame-aligned annotations.

    ### Video Metadata

    The JSON format allows you to specify `videoMetadata` for video files. `videoMetadata` is essential information used by the Label Editor and is crucial for aligning annotations to the correct frame.

    <Info>When the `videometadata` flag is included in the [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format), we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.</Info>

    <Note>
      `videoMetadata` must be specified when a [Strict client-only access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access) integration is used. In all other cases `videoMetadata` is optional.

      Encord assumes the `videoMetadata` is correct and our servers do not download or pre-process your data. This is particularly useful for customers with strict data compliance concerns.
    </Note>

    <Note>`videoMetadata` is distinct from `clientMetadata`. `videoMetadata` is required for videos when using *Strict client-only access*, while `clientMetadata` is optional and can be included for all types of data.</Note>

    One way to find the required metadata is shown below. Run the following commands in your terminal.

    * `ffmpeg -i 'video_title.mp4'` to retrieve fps, duration, width, and height:

    <div>
      <img />
    </div>

    * `ls -l 'video_title.mp4'` to retrieve the file size:

    <div>
      <img />
    </div>

    <AccordionGroup>
      <Accordion title="Example JSON including video metadata">
        ```json theme={"dark"}
        {
        "videos": [
          {
            "objectUrl": "video_file.mp4",
            "videoMetadata": {
                "fps": 23.98,
                "duration": 29.09,
                "width": 1280,
                "height": 720,
                "file_size": 5468354,
                "mime_type": "video/mp4"
            }
          }
        ]
        }

        ```

        * **fps**: Frames per second.
        * **duration**: Duration of the video (in seconds).
        * **width / height**: Dimensions of the video (in pixels).
        * **file\_size**: The size of the file (in bytes).
        * **mime\_type**: Specifies the file type extension according to the MIME standard.
      </Accordion>
    </AccordionGroup>

    ### Image Metadata

    The JSON format allows you to specify `imageMetadata` for image files. `imageMetadata` contains essential information used by the Label Editor and is crucial for aligning annotations to the correct image properties.

    <Info>When the `imageMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.</Info>

    <Note>`imageMetadata` must be specified when a [Strict client-only access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access) integration is used. In all other cases, `imageMetadata` is optional.</Note>

    ```json theme={"dark"}
    {
      "images": [
        {
          "objectUrl": "s3://my_image.jpg",
          "imageMetadata": {
            "mimeType": "image/jpg",
            "fileSize": 124,
            "width": 640,
            "height": 480
          }
        }
      ]
    }
    ```

    * **width / height**: Dimensions of the video (in pixels).
    * **file\_size**: The size of the file (in bytes).
    * **mime\_type**: Specifies the file type extension according to the MIME standard.

    ### Audio Metadata

    The JSON format allows you to specify `audioMetadata` for audio files. `audioMetadata` contains essential information used by the Label Editor and is crucial for aligning annotations to the correct audio properties.

    <Info>When the `audioMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.</Info>

    <Note>`audioMetadata` must be specified when a [Strict client-only access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access) integration is used. In all other cases, `audioMetadata` is optional.</Note>

    ```json theme={"dark"}
    {
      "audio": [
        {
          "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file_001.mp3",
          "audioMetadata": {
            "duration": 23.02,
            "file_size": 2900000,
            "mime_type": "audio/mp3",
            "sample_rate": 44100,
            "bit_depth": 24,
            "codec": "mp3",
            "num_channels": 2
            }
        }
      ]
    }
    ```

    * **duration**: Length of the audio file (in seconds).
    * **file\_size**: The size of the file (in bytes).
    * **mime\_type**: Specifies the file type extension according to the MIME standard.
    * **sample\_rate**: The number of samples per second in the audio file (in Hz).
    * **bit\_depth**: The number of bits per sample, representing audio resolution.
    * **codec**: The format used to encode the audio (e.g., "mp3").
    * **num\_channels**: The number of audio channels (e.g., 1 for mono, 2 for stereo).

    ### DICOM and NIfTI Metadata

    <Note>
      Encord does not currently support Strict Client-only Access for NIfTI files.
    </Note>

    Using Strict Client-only Access with DICOM files in Encord requires using the following script with `dicom_metadata` in a JSON file.

    <CodeGroup>
      ```python upload_dicom_strict_client_only_access.py theme={"dark"}
      import json
      import os
      from typing import List, Any

      from encord import EncordUserClient, Project
      import dotenv
      from encord.orm.dataset import LongPollingStatus
      from encord.orm.storage import CustomerProvidedDicomSeriesDicomFileMetadata, DataUploadDicomSeriesDicomFile, \
          DataUploadItems, DataUploadDicomSeries

      import json
      from typing import List, Dict, Optional


      def clean_dicom_metadata(metadata: Dict[str, Any]) -> Dict[str, Optional[Dict]]:
          """
          Clean DICOM metadata by converting string 'None' to actual None values
          and ensuring all values are either dicts or None.
          """
          cleaned = {}

          for tag_key, tag_value in metadata.items():
              if tag_value == 'None' or tag_value is None:
                  cleaned[tag_key] = None
              elif isinstance(tag_value, dict):
                  cleaned[tag_key] = tag_value
              else:
                  # For any other type, set to None
                  cleaned[tag_key] = None

          return cleaned


      def load_dicom_series_from_json(json_path: str) -> List[DataUploadDicomSeries]:
          """
          Load DICOM series data from JSON and convert to DataUploadDicomSeries objects.

          Args:
              json_path: Path to the JSON file containing DICOM series data

          Returns:
              List of DataUploadDicomSeries objects
          """
          with open(json_path, 'r') as f:
              data = json.load(f)

          series_list = []

          for series in data.get('dicom_series', []):
              # Extract series title
              series_title = series.get('title')

              # Process metadata for this series
              metadata = None
              if 'dicom_metadata' in series and series['dicom_metadata']:
                  cleaned_tags = clean_dicom_metadata(series['dicom_metadata'])
                  metadata = CustomerProvidedDicomSeriesDicomFileMetadata(
                      tags=cleaned_tags
                  )

              # Collect all DICOM files for this series
              dicom_files = []
              for key, value in series.items():
                  if key.startswith('objectUrl_'):
                      # Extract file index from key
                      file_index = key.replace('objectUrl_', '')

                      # Create individual file title
                      file_title = f"{series_title}_file_{file_index}" if series_title else f"file_{file_index}"

                      # Create the DICOM file object
                      dicom_file = DataUploadDicomSeriesDicomFile(
                          url=value,
                          title=file_title,
                          dicom_metadata=metadata
                      )

                      dicom_files.append(dicom_file)

              # Create the series object with all its files
              if dicom_files:  # Only create series if it has files
                  dicom_series = DataUploadDicomSeries(
                      dicom_files=dicom_files,
                      title=series_title,
                      client_metadata={},  # Add any custom metadata here if needed
                      external_file_type="DICOM"
                  )
                  series_list.append(dicom_series)

          return series_list

      dotenv.load_dotenv()

      SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
      FOLDER_HASH = "00000000-0000-0000-0000-000000000000" # Replace with the unique hash for the destination Folder
      INTEGRATION_HASH = "00000000-0000-0000-0000-000000000000" # Replace with the unique hash for the integration
      JSON_FILE_PATH = "/Users/chris-encord/dicom_to_upload.json" # Replace with file path to the JSON file

      #Authenticate using the path to your private key
      client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path=SSH_PATH)

      storage_folder = client.get_storage_folder(FOLDER_HASH)

      # Specify the integration you want to use by replacing <integration_title> with the integration title
      integrations = client.get_cloud_integrations(filter_integration_uuids=[INTEGRATION_HASH])
      integration = integrations[0].id

      dicom_series_for_upload = load_dicom_series_from_json(JSON_FILE_PATH)

      # Initiate cloud data registration to the storage folder
      upload_job_id = storage_folder.add_private_data_to_folder_start(
          integration_id=integration, private_files=DataUploadItems(dicom_series=dicom_series_for_upload), ignore_errors=True
      )

      # timeout_seconds determines how long the code waits after initiating upload before checking the upload status
      res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=30)
      print(f"Execution result: {res}")

      if res.status == LongPollingStatus.PENDING:
          print("Upload is still in progress, try again later!")
      elif res.status == LongPollingStatus.DONE:
          print("Upload completed")
          if res.unit_errors:
              print("The following URLs failed to upload:")
              for e in res.unit_errors:
                  print(e.object_urls)
      else:
          print(f"Upload failed: {res.errors}")

      ```

      ```json dicom_to_upload.json theme={"dark"}
      {
        "dicom_series": [
          {
            "title": "Series01",
            "objectUrl_0": "https://storage.googleapis.com/gcp-strict-client-access/dicom/MR.1.2.246.352.221.576299240410465369217801204063372607904.dcm",
            "dicom_metadata": {
              "00280030": {
                "vr": "DS",
                "Value": [
                  1.0,
                  1.0
                ]
              },
              "00281050": {
                "vr": "DS",
                "Value": [
                  179.0
                ]
              },
              "00280008": "None",
              "00209116": "None",
              "00181164": "None",
              "00280004": {
                "vr": "CS",
                "Value": [
                  "MONOCHROME2"
                ]
              },
              "00281051": {
                "vr": "DS",
                "Value": [
                  359.0
                ]
              },
              "00200037": {
                "vr": "DS",
                "Value": [
                  -0.0,
                  1.0,
                  0.0,
                  -0.0,
                  -0.0,
                  -1.0
                ]
              },
              "52009229": "None",
              "00100020": {
                "vr": "LO",
                "Value": [
                  "fc065_fmri_140207"
                ]
              },
              "00280010": {
                "vr": "US",
                "Value": [
                  256
                ]
              },
              "00289110": "None",
              "00200013": {
                "vr": "IS",
                "Value": [
                  1
                ]
              },
              "0020000D": {
                "vr": "UI",
                "Value": [
                  "1.2.840.113619.6.283.4.679947340.8065.1391798290.307"
                ]
              },
              "00181114": "None",
              "00200032": {
                "vr": "DS",
                "Value": [
                  100.96,
                  -140.977,
                  153.398
                ]
              },
              "00080018": {
                "vr": "UI",
                "Value": [
                  "1.2.840.113619.2.283.6945.3146400.16119.1391477777.667"
                ]
              },
              "52009230": "None",
              "00280011": {
                "vr": "US",
                "Value": [
                  256
                ]
              },
              "00209113": "None",
              "00180050": {
                "vr": "DS",
                "Value": [
                  1.2
                ]
              },
              "0020000E": {
                "vr": "UI",
                "Value": [
                  "1.2.840.113619.2.283.6945.3146400.21673.1391477673.97"
                ]
              }
            }
          }
        ]
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## Custom Signed URL Expiration Time

A custom signed URL expiration time allows you to set the duration that an integration's pre-signed URL remains valid.

<Note>Custom signed URL expiration times are only available for AWS, GCP, and OTC integrations.</Note>

Shorter signed URL expiration times are more secure, but can negatively impact the annotation and review experiences in the Label Editor. Ensure that the URL expiration time exceeds the amount of time that files from the integration take to annotate and review. The default value for signed URL expiration times when creating an integration is 1 week.

### Setting Custom Signed URL Expiration Times

To set up a custom signed URL expiration time for a new integration:

1. Click the *Custom signed URL integration time* checkbox in the *Advanced settings* when setting up your GCP, AWS, or OTC integration.

2. Set the duration for which pre-signed URLs should remain valid. We recommend configuring the URL expiration time to exceed the time required to annotate and review files from the integration in the Label Editor.

<div>
  <img />
</div>

### Edit Custom Signed URL Expiration Times

<Note>Custom signed URL expiration times are only available for AWS, GCP, and OTC integrations. For Azure integrations,[expired SAS tokens must be updated regularly](/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration#updating-expired-account-level-sas-tokens).</Note>

To change the custom signed URL expiration time for an existing integration:

1. Click the three dots icon on your integration.

2. Select **Update Signed Url Expiration**.

<div>
  <img />
</div>

3. Set the duration for which pre-signed URLs should remain valid. We recommend configuring the URL expiration time to exceed the time required to annotate and review files from the integration in the Label Editor.

***

## View and Join Integrations in Your Workspace

Workspace Admins can search for and join any [data integration](/platform-documentation/General/annotate-data-integrations) that exists within the Workspace.

**To search and join integrations**:

1. Navigate to the *Integrations* of the Encord platform.
2. Click **All Encord integrations**.
3. Click **Join integration** to join the integration.

<Tip>
  * Integrations can be filtered by the owner of the integration.
  * See all integrations you belong to by clicking the *Filter by* search bar, and selecting *My integrations only*.
</Tip>

<div>
  <img />
</div>

When a Workspace Admin joins an integration, they are automatically assigned the *Admin* [user role for that integration](/platform-documentation/General/annotate-data-integrations#user-roles-and-permissions).

<Tip>Integrations can ONLY be deleted by the creator of the integration. Even admins cannot delete an integration if they did not create the integration.</Tip>

***

## Fix Buffering Issues

A number of factors determine how fast remote content renders and displays in a web browser:

* [Geographical distance from host bucket](#geographical-distance-from-host).
* [Local internet speed](#local-internet-speed).
* Use of a [Virtual Private Network (VPN)](#vpns).
* The [bitrate of the video](#high-bitrates-in-videos) file being requested.

While these factors are outside of Encord's influence, we have put together a set of common issues when loading data from private clouds, along with possible solutions to improve your user experience.

<Note>You can see the speed that a video downloads at the bottom of the 'editor pane' in the Label Editor on Encord's platform. The speed also displays the download speed required to display a video without buffering.</Note>

### Geographical distance from host

The physical distance between you and the server hosting your data affects how quickly content is accessed. For example, hosting an Amazon S3 bucket in the EU (London) eu-west-2 region may cause latency for users in India or Brazil due to the long travel distance for the data.

<img />

To fix the issue, make sure that users always connect to their closest server. This reduces the time it takes for data to travel from one place to another. Setting this up, differs between cloud storage providers.

<img />

<AccordionGroup>
  <Accordion title="Amazon S3">
    ### Caching Header

    Caching MUST be enabled on the parent folder containing the objects you want to label. This is done by [setting a cache-control header](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html#ExpirationAddingHeadersInS3). If you do not set a cache-control header on all objects, this can lead to data loading slowly on our platform.

    ### Multi-Region Access Points

    AWS allows you to set up [Multi-Region Access Points](https://aws.amazon.com/s3/features/multi-region-access-points/) that provides a single global end point to access a replicated dataset spanning multiple S3 buckets. This means that users all around the world are always connected to their closest server when accessing content from an S3 bucket.

    To make this work in Encord:

    1. Set up Multi-Region Access Point on Amazon S3. Their step-by-step guide can be found [here](https://aws.amazon.com/getting-started/hands-on/getting-started-with-amazon-s3-multi-region-access-points/).

    2. Integrate your Multi-Region Access Point with Encord. The process is documented [here](/platform-documentation/General/annotate-data-integrations#create-a-multi-region-access-point-integration).

    3. Add data using the Multi-Region Access Point integration. When specifying which files to register in your JSON file, make sure to use the ARN of the Multi-Region Access Point followed by the object name, instead of the object URL, as documented [here](/platform-documentation/Curate/add-files/index-register-cloud-data#when-using-a-multi-region-access-point).
  </Accordion>

  <Accordion title=" GCP ">
    * You can check your latency to Google Cloud regions [here](https://www.gcping.com), and the latency between different regions [here](https://lookerstudio.google.com/reporting/fc733b10-9744-4a72-a502-92290f608571/page/70YCB) to assess the connection speed to your GCP bucket.

    <Tip>
      We recommend using the ['Premium' network service tier](https://cloud.google.com/network-tiers#tab1) if you experience buffering issues while using data stored on GCP. This ensures a high-performing network experience with a global footprint.
    </Tip>
  </Accordion>
</AccordionGroup>

### Local Internet Speed

Test your internet connection to make sure it is fast enough to download your video from cloud storage without buffering. Consistently low internet speeds might mean your provider isn't providing you with high enough internet speeds to load large quantities of data from your cloud storage.

You can see the speed that a video downloads at the bottom of the 'editor pane' in the Label Editor on Encord's platform. The speed also displays the download speed required to display a video without buffering.

### VPNs

VPNs can slow down your connection by requiring the data travel through the VPN's server before arriving to you.

<Tip>
  We recommend turning off your VPN when using Encord's platform, if you are experiencing buffering issues.
</Tip>

### High Bitrates in Videos

Videos vary widely in frame rate, compression, definition, and size. The most important factor in determining how quickly a remote video loads is its bitrate. A higher bitrate requires more data to load per second of video.

![High bitrates](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/high-bitrate.png)

<Tip>
  To make sure videos load and display quickly in the Label Editor:

  1. A Tasker's download speed from private cloud storage has to be at least 3-4 times the video bitrate.
  2. Have enough keyframes to ensure smooth frame-by-frame navigation (roughly every 50 frames for high-resolution videos).
</Tip>

Lowering a video's bitrate reduces the time it takes to load from your cloud storage. This can be achieved using tools such as FFmpeg. See our documentation on [resizing videos](/platform-documentation/General/general-supported-data#resizing-videos) for more information.

<Warning>Lowering the bitrate involves decreasing the video quality and is only suitable for customers not reliant on high-quality videos.</Warning>

### Updating Terraform Configuration

<Note>
  This section only applies when using a Terraform cloud integration.
</Note>

If you configure your integration manually (for example, setting CORS policies in the AWS or GCP console) and then later apply a Terraform script, the script can overwrite your manual changes. This may cause your integration to stop working. Always ensure your Terraform configuration file includes all necessary settings, especially for CORS policies.


# AWS S3
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-aws-integration



Watch our video tutorial on creating AWS S3 integrations, or follow the step-by-step guide below for even more details.

<AccordionGroup>
  <Accordion title=" Video Tutorial - Creating an AWS integration ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

***

In order to integrate with AWS S3, you must:

1. Create a new AWS integration in Encord.
2. [Create a permission policy](#2-create-a-permission-policy) for your resources to allow Encord the necessary access.
3. [Create a role for Encord](#3-create-a-role-for-encord) and attach the policy so that Encord can access those resources.
4. [Activate Cross-origin resource sharing](#4-allow-cross-origin-resource-sharing-cors) to allow Encord to access those resources from a web browser.
5. [Configure Cache-Control on your bucket or objects](#5-update-metadata-settings-in-aws)
6. [Test the integration](#6-test-the-integration) to ensure it works.

<Info>
  Create an S3 bucket to store your files if you have not done so already. The S3 bucket must have [STS available](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) and enabled.

  * Set your bucket permissions to block all public access.
  * Ensure that the [Storage Class](https://aws.amazon.com/s3/storage-classes/) of all files is set to 'S3 Standard'.
</Info>

## 1. Start setting up the AWS integration

1. Navigate to [Workspace Settings](/platform-documentation/General/general-workspace-settings#workspace-settings) > Cloud Buckets and click **+New integration**.

<div>
  <img />
</div>

<Warning>
  Do not close this tab or window until you have finished the integration process. We advise opening AWS in a separate tab.
</Warning>

2. Select **AWS S3**.

3. Give your integration a meaningful title.

<div>
  <img />
</div>

***

## 2. Create a Permission Policy

You can create a permission policy using the AWS cli or using the AWS Console UI.

### Use the AWS cli

Log in to AWS cli and run the following code.

<CodeGroup>
  ```bash Linux and macOS theme={"dark"}

  # 1) Set your variables
  POLICY_NAME="S3ReadWriteYourBucket"
  BUCKET="your-bucket"   # Replace this with your AWS bucket name

  # 2) Create the policy JSON (policy.json)
  cat > policy.json <<EOF
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
          "s3:PutObject",
          "s3:GetObject",
          "s3:ListBucket"
        ],
        "Resource": [
          "arn:aws:s3:::$BUCKET",
          "arn:aws:s3:::$BUCKET/*"
        ]
      }
    ]
  }
  EOF

  # 3) Create the IAM policy
  aws iam create-policy \
    --policy-name "$POLICY_NAME" \
    --policy-document file://policy.json

  ```

  ```bash Windows Powershell theme={"dark"}
  # 1) Set your variables
  $PolicyName = "S3ReadWriteYourBucket"
  $Bucket = "your-bucket"   # <-- change this

  # 2) Create the policy JSON (policy.json)
  $policy = @"
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
          "s3:PutObject",
          "s3:GetObject",
          "s3:ListBucket"
        ],
        "Resource": [
          "arn:aws:s3:::$Bucket",
          "arn:aws:s3:::$Bucket/*"
        ]
      }
    ]
  }
  "@
  $policy | Out-File -FilePath policy.json -Encoding UTF8

  # 3) Create the IAM policy
  aws iam create-policy `
    --policy-name $PolicyName `
    --policy-document file://policy.json

  ```
</CodeGroup>

### Use the AWS Console UI

1. In Encord, copy the JSON from Step 2 of the integration.

   For example:

   ```json theme={"dark"}
   {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket",
                "arn:aws:s3:::your-bucket/*"
            ]
        }
    ]
    }
   ```

2. In AWS, navigate to Identity and Access Management (IAM) and select  *Policies*.

3. Click **Create policy** to create a new policy.

4. Select **JSON** as the *Policy editor*

<div>
  <img />
</div>

4. Paste the JSON you copied from Encord into the *Policy editor*, replacing the `arn:aws:s3YourBucket` value for *Resource* with your bucket's Amazon Resource Name (ARN). The ARN can be found in the *Properties* tab of your S3 bucket. When pasting your bucket ARN into the JSON policy editor, ensure that the *Resource* value ends in `/*`. Click the **Next** button to continue.

<Info>
  * `s3:PutObject` is needed for features that require write permissions, including [re-encoding data](/platform-documentation/General/general-supported-data#re-encode-videos) and creating [image sequences](/platform-documentation/General/general-supported-data#image-sequences).

  * `s3:ListBucket` is OPTIONAL. **Cloud Synced Folders** requires `s3:ListBucket` read permissions to sync data stored in your buckets to Encord Cloud Synced Folders .
</Info>

<div>
  <img />
</div>

<div>
  <img />
</div>

5. Add any tags according to your Workspace's resource tagging policy, and give your policy a descriptive name (used when creating a role for Encord). Click  **Create policy** to finish creating your policy.

<div>
  <img />
</div>

6. Click  **Create policy** to finish creating your policy.

***

## 3. Create a Role for Encord

1. In AWS, navigate to *Roles* and click the **Create role** button.

<div>
  <img />
</div>

2. For *Trusted entity type* select **AWS Account** and in the *An AWS Account* section select **Another AWS account**.

<div>
  <img />
</div>

3. In Encord copy the *Encord AWS account ID* from Step 3 of the integration (shown below), and paste it into the *Account ID* field in AWS (shown above). In AWS, check *Require external ID* under *Options* to reveal the *External ID* field.

4. Navigate back to Encord and click **Generate and copy** to copy an External ID.

<div>
  <img />
</div>

5. In AWS, paste the External ID you generated into the *External ID* field and click **Next**.

<div>
  <img />
</div>

6. Select the IAM policy you created in Step 2 and click **Next** to attach it to the role.

<div>
  <img />
</div>

7. Give your role a descriptive name and click the **Create role** button.

8. Copy the Role ARN and the name of the role you just created.

<div>
  <img />
</div>

9. In Encord, paste the name of the role and the Role ARN into Step 3 of the integration.

<div>
  <img />
</div>

***

## 4. Allow Cross-origin resource sharing (CORS)

<Warning>
  If you use Infrastructure as Code tools like Terraform, they can overwrite your manual CORS settings. To prevent this, always include the correct CORS policy in your Terraform configuration file.
</Warning>

<Warning>
  Applying Encord required CORS settings may overwrite existing configurations on your cloud storage bucket. If your bucket already has CORS settings, make sure to append Encord’s required settings instead of replacing them.
</Warning>

1. In Encord, expand Step 4 of the integration. Copy the CORS JSON policy.

<CodeGroup>
  ```json Global theme={"dark"}
  [
      {
          "AllowedHeaders": [
              "*"
          ],
          "AllowedMethods": [
              "GET",
              "HEAD"
          ],
          "AllowedOrigins": [
              "https://app.encord.com",
              "https://api.encord.com",
              "https://api.us.encord.com",
              "https://app.us.encord.com"
          ],
          "ExposeHeaders": [
              "Content-Length",
              "Content-Range",
              "Accept-Ranges",
              "ETag",
              "Content-Type",
              "Last-Modified"
          ],
          "MaxAgeSeconds": 3600
      }
  ]
  ```

  ```json EU theme={"dark"}
  [
      {
          "AllowedHeaders": [
              "*"
          ],
          "AllowedMethods": [
              "GET",
              "HEAD"
          ],
          "AllowedOrigins": [
              "https://app.encord.com",
              "https://api.encord.com"
          ],
          "ExposeHeaders": [
              "Content-Length",
              "Content-Range",
              "Accept-Ranges",
              "ETag",
              "Content-Type",
              "Last-Modified"
          ],
          "MaxAgeSeconds": 3600
      }
  ]
  ```

  ```json US theme={"dark"}
  [
      {
          "AllowedHeaders": [
              "*"
          ],
          "AllowedMethods": [
              "GET",
              "HEAD"
          ],
          "AllowedOrigins": [
              "https://api.us.encord.com",
              "https://app.us.encord.com"
          ],
          "ExposeHeaders": [
              "Content-Length",
              "Content-Range",
              "Accept-Ranges",
              "ETag",
              "Content-Type",
              "Last-Modified"
          ],
          "MaxAgeSeconds": 3600
      }
  ]
  ```
</CodeGroup>

<Note>
  These rules allow byte-range requests (`GET`/`HEAD`) and expose the range and caching headers — `Content-Range`, `Content-Length`, `Accept-Ranges`, `ETag`, `Content-Type`, `Last-Modified` — that large scene files (such as MCAP) need in order to stream in chunks directly in the browser. Without them, Scenes stay stuck on *"Loading content…"* and report that the scene has no images.
</Note>

2. Navigate to the *Permissions* tab of your S3 bucket. Scroll to the bottom of the page and click **Edit** in the *Cross-origin resource sharing (CORS)* heading.

<div>
  <img />
</div>

3. Paste the JSON into the editor that pops up. Click **Save changes** to finish settings up CORS.

<div>
  <img />
</div>

4. Navigate back to Encord and click **Create** to finish the integration set up.

<Tip>We have a few [helpful scripts and examples](/platform-documentation/Curate/add-files/index-register-cloud-data#helpful-scripts-and-examples) to get you started creating Datasets from your Amazon S3 bucket.</Tip>

<Warning>
  Integration tests might temporarily be unsuccessful due to AWS data processing delays after setup. These delays can take up to 24 hours to resolve, after which labeling can begin.
</Warning>

***

## 5. Update Metadata Settings in AWS

Add Cache-Control headers to your AWS folders or objects, following the AWS instructions [here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html#ExpirationAddingHeadersInS3). Adding Cache-Control headers significantly increases the speed at which your files load in the Label Editor.

<Tip>
  When you copy an object to change its cache control header, select "Specify Settings" to preserve the original content type.

  <div>
    <img />
  </div>
</Tip>

## 6. Test the Integration

<Note>
  This test confirms Encord can assume the specified role, but does not guarantee bucket access. If data onboarding is unsuccessful despite passing the test, verify Encord's bucket permissions and the accuracy of your object URLs.
</Note>

1. Click the **Run a test** button on the integration, to test the integration.

<div>
  <img />
</div>

2. Paste the URL of any object in the bucket and click **Check Encord can access this URL**. If the test is successful a green tick appears next to *Encord infrastructure* and *This machine*.

<Warning>
  Not setting up the cache-control header in Step 5 can result in the `Cache policy not set` error when testing the integration.
</Warning>

<Warning>
  Integration tests might temporarily be unsuccessful due to AWS data processing delays after setup. These delays can take up to 24 hours to resolve, after which labeling can begin.
</Warning>

***

## Register AWS Data

<Tip>We recommend [setting the expiration time for signed URLs](/platform-documentation/General/annotate-data-integrations#edit-custom-signed-url-expiration-times) to be greater than the time it takes to complete an annotation task.</Tip>

Navigate to the <a href="/platform-documentation/Curate/add-files/index-register-cloud-data">Register cloud data</a> page for guidance on how to register files stored in AWS.

***

## Create a Multi-Region Access Point Integration

Using Multi-Region Access Points requires you to do a few things differently when setting up an AWS integration.

1. [When creating a permission policy](#2-create-a-permission-policy) for your multi-region access point in AWS, make sure to list the ARN of the Multi-Region Access Point, as well as the ARNs of all constituent buckets in the JSON.

<AccordionGroup>
  <Accordion title=" Example JSON ">
    ```json theme={"dark"}
    {
     "Version": "2012-10-17",
     "Statement": [
         {
             "Sid": "VisualEditor0",
             "Effect": "Allow",
             "Action": [
                 "s3:PutObject",
                 "s3:GetObject",
                 "s3:ListBucket"
             ],
             "Resource": [
                 "arn:aws:s3:::your-bucket",
                 "arn:aws:s3:::your-bucket/*",
                 "Bucket-1-ARN/*",
                 "Bucket-2-ARN/*",
                 "Bucket-3-ARN/*"
             ]
         }
     ]
     }

    ```
  </Accordion>
</AccordionGroup>

2. Make sure you [create a CORS policy](#4-allow-cross-origin-resource-sharing-cors) for every bucket that is included in your Multi-Region Access Point.

3. When uploading data to a dataset using the Multi-Region Access Point integration, make sure your JSON file is formatted correctly for use with a Multi-Region Access point - as documented [here](/platform-documentation/Curate/add-files/index-register-cloud-data#when-using-a-multi-region-access-point).

***

## Terraform your AWS S3 Integration

<Note>
  This guide is intended as a supplement to the Terraform documentation provided by Hashicorp [here](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket).
</Note>

Terraforming must be performed in conjunction with the setting up your cloud integration. Do not simply copy and paste the example below. Use the example as a template for Terraforming your private cloud integration.

<Warning>
  Terraforming your integration can overwrite your integration set up causing your integration to stop working. Always ensure your Terraform configuration file includes all necessary settings, especially for CORS policies.
</Warning>

To integrate with Encord, you must create:

1. An S3 Bucket
2. An IAM Policy
3. An IAM Role
4. A CORS Policy

Below are some examples of how this might look:

#### Declare your Terraform providers

In the below example, we're using Hashicorp's AWS provider `aws` and the `tfvars` utility that allows us to neatly define values to pass into variables.

We also define an alias as well as a Region for the AWS provider, which needs to match the location in which you want your bucket to be provisioned.

```markdown theme={"dark"}
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.1.0"
    }
    tfvars = {
      source  = "innovationnorway/tfvars"
      version = "0.0.1"
    }
  }
}

provider "aws" {
  alias  = "default"
  region = var.aws_region
}
```

***

#### Declaring your variables

In your `variables.tf` file, you will need to define the variables into which you want to pass values. An example is below:

```markdown theme={"dark"}
variable "bucket_name" {
  description = "Name of the AWS S3 Bucket"
  type        = string
}

variable "policy_name" {
  description = "Name of the IAM Policy"
  type        = string
}

variable "role_name" {
  description = "Name of the IAM Role"
  type        = string
}

variable "external_aws_account_id" {
  description = "Account ID of the external AWS account you're connecting to - default value 312435012576 for Encord"
  type        = string
  default     = "312435012576"
}

variable "external_id" {
  description = "External account id - this is unique to your integration and can be found in the integration setup modal"
  type        = string
}

variable "aws_region" {
  description = "AWS Region in which bucket should be provisioned"
  type        = string
  default     = "eu-west-2"
}
```

***

#### Defining your variables in a `.tfvars` file to avoid having to manually edit the Terraform files

Since we've opted to use `tfvars` we need to create a corresponding `.tfvars` file and specify some values we wish to pass into the variables you just defined:

```markdown theme={"dark"}
bucket_name             = "encord-test-bucket"
policy_name             = "encord-test-policy"
role_name               = "encord-test-role"
external_aws_account_id = "312435012576"      # This is the same for every integration since it is Encord's AWS account ID
external_id             = "external-id" # This comes from the integration setup modal within the Encord application and is unique for each integration you set up
aws_region              = "eu-west-2"          # Change this to the appropriate region in which your bucket is to be created
```

***

#### Creating the required resources

The resources you need to create include:

1. The AWS S3 bucket itself
2. The AWS Bucket CORS Policy to allow Cross Origin Resource Sharing with the Encord domains
3. The IAM Role
4. The IAM Policy
5. The IAM Policy attachment that binds the Role to the Policy

#### Defining the Bucket, Bucket ACL, and Bucket CORS Policy:

<CodeGroup>
  ```markdown Global theme={"dark"}
  resource "aws_s3_bucket" "bucket_name" {
    bucket = var.bucket_name
  }

  resource "aws_s3_bucket_cors_configuration" "bucket_cors_policy" {
    bucket = var.bucket_name
    cors_rule {
      allowed_headers = [
        "*"
      ]

      allowed_methods = ["GET",
      "PUT"] # The PUT method here is not necessary unless you intend to re-encode videos or work with image sequences

      allowed_origins = [
        "https://app.encord.com",
        "https://api.encord.com"
      ]
      max_age_seconds = 3600
    }
  }
  ```

  ```markdown US theme={"dark"}
  resource "aws_s3_bucket" "bucket_name" {
    bucket = var.bucket_name
  }

  resource "aws_s3_bucket_cors_configuration" "bucket_cors_policy" {
    bucket = var.bucket_name
    cors_rule {
      allowed_headers = [
        "*"
      ]

      allowed_methods = ["GET",
      "PUT"] # The PUT method here is not necessary unless you intend to re-encode videos or work with image groups

      allowed_origins = [
        "https://app.us.encord.com",
        "https://api.us.encord.com"
      ]
      max_age_seconds = 3600
    }
  }
  ```
</CodeGroup>

***

#### Defining the IAM Policy:

```markdown theme={"dark"}
resource "aws_iam_policy" "encord-test-policy" {
  name        = var.policy_name
  path        = "/"
  description = "video testing S3 policy"
  policy      = <<POLICY
{
 "Version": "2012-10-17",
 "Statement": [
     {
         "Effect": "Allow",
         "Action": [
             "s3:PutObject",
             "s3:GetObject",
             "s3:ListBucket"
         ],
         "Resource": [
             "arn:aws:s3:::your-bucket",
             "arn:aws:s3:::your-bucket/*"
         ]
     }
 ]
 }
POLICY
}
```

```markdown theme={"dark"}
resource "aws_iam_role" "encord-test-role" {
  name               = var.role_name
  path               = "/"
  assume_role_policy = <<POLICY
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::${var.external_aws_account_id}:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "${var.external_id}"
        }
      }
    }
  ]
}
POLICY
}
```

***

#### Attaching the Role to the Policy:

```markdown theme={"dark"}
resource "aws_iam_policy_attachment" "encord-test-policy-policy-attachment" {
  policy_arn = aws_iam_policy.encord-test-policy.arn
  roles      = [var.role_name]
  name       = "${var.policy_name}-policy-attachment"
}
```

Before applying any changes, run `terraform plan` to preview the changes and check you are happy with them.

Once your Terraform has been applied, return to the Encord application, and test your integration.

***

The entire resources file `s3-resources.tf` now looks like this:

<CodeGroup>
  ```markdown Global theme={"dark"}
  resource "aws_s3_bucket" "bucket_name" {
    bucket = var.bucket_name
  }

  resource "aws_s3_bucket_cors_configuration" "bucket_cors_policy" {
    bucket = var.bucket_name
    cors_rule {
      allowed_headers = [
        "*"
      ]

      allowed_methods = ["GET",
      "PUT"] # The PUT method here is not necessary unless you intend to re-encode videos or work with image sequences

      allowed_origins = [
        "https://app.encord.com",
        "https://api.encord.com",
        "https://app.in.encord.com"
      ]
      max_age_seconds = 3600
    }
  }


  resource "aws_iam_policy" "encord-test-policy" {
    name        = var.policy_name
    path        = "/"
    description = "video testing S3 policy"
    policy      = <<POLICY
  {
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "s3:PutObject",
               "s3:GetObject",
               "s3:ListBucket"
           ],
           "Resource": [
               "arn:aws:s3:::your-bucket",
               "arn:aws:s3:::your-bucket/*"
           ]
       }
   ]
   }
  POLICY
  }


  resource "aws_iam_role" "encord-test-role" {
    name               = var.role_name
    path               = "/"
    assume_role_policy = <<POLICY
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::${var.external_aws_account_id}:root"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {
            "sts:ExternalId": "${var.external_id}"
          }
        }
      }
    ]
  }
  POLICY
  }


  resource "aws_iam_policy_attachment" "encord-test-policy-policy-attachment" {
    policy_arn = aws_iam_policy.encord-test-policy.arn
    roles      = [var.role_name]
    name       = "${var.policy_name}-policy-attachment"
  }
  ```

  ```markdown US theme={"dark"}
  resource "aws_s3_bucket" "bucket_name" {
    bucket = var.bucket_name
  }

  resource "aws_s3_bucket_cors_configuration" "bucket_cors_policy" {
    bucket = var.bucket_name
    cors_rule {
      allowed_headers = [
        "*"
      ]

      allowed_methods = ["GET",
      "PUT"] # The PUT method here is not necessary unless you intend to re-encode videos or work with image groups

      allowed_origins = [
        "https://app.us.encord.com",
        "https://api.us.encord.com"
      ]
      max_age_seconds = 3600
    }
  }


  resource "aws_iam_policy" "encord-test-policy" {
    name        = var.policy_name
    path        = "/"
    description = "video testing S3 policy"
    policy      = <<POLICY
  {
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "s3:PutObject",
               "s3:GetObject",
               "s3:ListBucket"
           ],
           "Resource": [
               "arn:aws:s3:::your-bucket",
               "arn:aws:s3:::your-bucket/*"
           ]
       }
   ]
   }
  POLICY
  }


  resource "aws_iam_role" "encord-test-role" {
    name               = var.role_name
    path               = "/"
    assume_role_policy = <<POLICY
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::${var.external_aws_account_id}:root"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {
            "sts:ExternalId": "${var.external_id}"
          }
        }
      }
    ]
  }
  POLICY
  }


  resource "aws_iam_policy_attachment" "encord-test-policy-policy-attachment" {
    policy_arn = aws_iam_policy.encord-test-policy.arn
    roles      = [var.role_name]
    name       = "${var.policy_name}-policy-attachment"
  }
  ```
</CodeGroup>


# Azure Blob
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration



<Note>
  Encord does not currently support Multi-Region Access Points for Azure.
</Note>

## 1. Set Up the Integration

1. In Encord, navigate to the *Integrations* section and click the **Add integration** button.

<div>
  <img />
</div>

2. Click on *Azure*.

3. Give your integration a meaningful name.

## 2. Register the Azure Storage Account

1. Paste the name of your Azure storage account into Step 2 of the integration.

<div>
  <img />
</div>

## 3. Select Authentication Type

Select your preferred method of authentication in Step 3 the Azure integration window.

* [Shared access signature](#method-1-generate-an-account-level-sas).
* [(Legacy) Azure service principal](#method-2-use-a-service-principal).

<div>
  <img />
</div>

## 4. Authenticate Azure

You can authenticate Azure in two different ways:

1. [Generating an account-level shared access signature (SAS)](#method-1-generate-an-account-level-sas).

2. [Using a service principal](#method-2-use-a-service-principal).

<Note>Using a service principal to authenticate requires admin privileges for the Azure account. </Note>

### Method 1: Generate an Account-Level SAS

1. In [Azure](https://portal.azure.com/#home), navigate to **Storage Accounts** under *Azure services* and select the storage account you wish to integrate.

<div>
  <img />
</div>

2. Next, click on **Shared access signature** in the *Security + networking* section.

<div>
  <img />
</div>

3. You must check the *Container* and *Object* checkboxes under the *Allowed resource types* heading. Ensure you add the necessary permissions:

* Read (required)
* List (required)
* Write (recommended)
* Add (recommended)
* Create (recommended)

<Note>*recommended* permissions are necessary to use some of our more advanced features such as [re-encoding data](/platform-documentation/General/general-supported-data#re-encode-videos), and [image sequences](/platform-documentation/General/general-supported-data#image-sequences).</Note>

4. Click **Generate SAS and connection string** when you are ready to generate your account-level SAS token.

<Warning>Your SAS token has a start and end date that can be adjusted, and is valid for the specified time period. Expired tokens must be [updated](#updating-expired-account-level-sas-tokens).</Warning>

<Tip>To avoid having to update the token frequently, set the expiration date to be more than one year.</Tip>

5. Paste the SAS token into Step 4 of the Azure integration window, in Encord.

<div>
  <img />
</div>

### Method 2: Use a Service Principal

Using a service principal to authenticate you require you to:

1. [Add the cord-integrator app to your Azure tenant](#add-the-cord-integrator-app-to-azure-tenant).
2. [Find your Azure tenant ID](#find-your-azure-tenant-id).

#### Add the cord-integrator App to Azure Tenant

There are three different ways to add the cord-integrator app to Azure tenant:

1. [Using a browser.](#add-the-cord-integrator-app-in-a-browser)

2. [Using Azure powershell.](#add-the-cord-integrator-app-via-azure-powershell)

3. [By granting storage account and container permissions to `cord-integrator`.](#grant-storage-account-and-container-permissions-to-cord-integrator)

<Note>You need to have admin privileges for your Azure account to authenticate via a service principal.</Note>

#### Add the cord-integrator App in a Browser

You can add the *cord-integrator* application in the *Settings* of the Encord app. If logged in to the Encord platform, you are redirected to the 'Azure integration' screen after the application was successfully added.

<img alt="Adding the 'cord-integrator' application to Azure tenant" />

#### Add the cord-integrator app via Azure Powershell

```
New-AzADServicePrincipal -ApplicationId ab859d51-5577-4d6d-9b87-544df597f38a

```

#### Grant Storage Account and Container Permissions to cord-integrator

The *cord-integrator* must be granted two types of permissions in order to function:

* The **Storage Blob Data Contributor** role at the container level
  <img alt="Adding the 'Storage Blob Data Contributor' role to the cord-integrator service principal" />
* The **Storage Blob Delegator** role at the storage account level
  <img alt="Adding the 'Storage Blob Delegator' role to the cord-integrator service principal at the storage account level" />

#### Find your Azure tenant ID

You can find the Azure Tenant ID in the <a href="https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview">Active Directory overview</a> of your Azure project.

<div>
  <img />
</div>

Paste the tenant ID into Step 4 of the Azure integrations window, after you have added the cord-integrator app, granted it storage account, and container permissions and located your Azure tenant.

<div>
  <img />
</div>

## 5. Create a CORS Configuration in Azure

<Warning>
  If you use Infrastructure as Code tools like Terraform, they can overwrite your manual CORS settings. To prevent this, always include the correct CORS policy in your Terraform configuration file.
</Warning>

<Warning>
  Applying Encord required CORS settings may overwrite existing configurations on your cloud storage bucket. If your bucket already has CORS settings, make sure to append Encord’s required settings instead of replacing them.
</Warning>

A [CORS configuration](https://learn.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services) must be applied to the Azure storage account you want to integrate with Encord. This enables Encord to request resources from the specified service account using a browser.

1. Navigate to the *Resource Sharing (CORS)* section under *Settings* of your storage account.

<img />

2. Input the following values in the *Blob service* tab of Resource Sharing (CORS) page:

<Tabs>
  <Tab title="Global">
    | Allowed origins             | Allowed methods                         |                      Allowed headers                      |                                       Exposed headers                                       | Max age |
    | --------------------------- | --------------------------------------- | :-------------------------------------------------------: | :-----------------------------------------------------------------------------------------: | :-----: |
    | `https://app.encord.com`    | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `If-Modified-Since`, `If-None-Match`, `If-Range`, `Range` | `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Last-Modified` |   3600  |
    | `https://api.encord.com`    | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `If-Modified-Since`, `If-None-Match`, `If-Range`, `Range` | `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Last-Modified` |   3600  |
    | `https://app.us.encord.com` | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `If-Modified-Since`, `If-None-Match`, `If-Range`, `Range` | `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Last-Modified` |   3600  |
    | `https://api.us.encord.com` | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `If-Modified-Since`, `If-None-Match`, `If-Range`, `Range` | `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Last-Modified` |   3600  |
  </Tab>

  <Tab title="EU">
    | Allowed origins          | Allowed methods                         |                      Allowed headers                      |                                       Exposed headers                                       | Max age |
    | ------------------------ | --------------------------------------- | :-------------------------------------------------------: | :-----------------------------------------------------------------------------------------: | :-----: |
    | `https://app.encord.com` | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `If-Modified-Since`, `If-None-Match`, `If-Range`, `Range` | `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Last-Modified` |   3600  |
    | `https://api.encord.com` | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `If-Modified-Since`, `If-None-Match`, `If-Range`, `Range` | `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Last-Modified` |   3600  |
  </Tab>

  <Tab title="US">
    | Allowed origins             | Allowed methods                         |                      Allowed headers                      |                                       Exposed headers                                       | Max age |
    | --------------------------- | --------------------------------------- | :-------------------------------------------------------: | :-----------------------------------------------------------------------------------------: | :-----: |
    | `https://app.us.encord.com` | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `If-Modified-Since`, `If-None-Match`, `If-Range`, `Range` | `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Last-Modified` |   3600  |
    | `https://api.us.encord.com` | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `If-Modified-Since`, `If-None-Match`, `If-Range`, `Range` | `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Last-Modified` |   3600  |
  </Tab>
</Tabs>

In the example above, preflight requests are valid for 1 hour. Use the 'Max Age' variable to adjust the number of seconds the browser is allowed to make requests before it must repeat the preflight request.

3. Click **Save** to save the CORS configuration.

4. Click **Create** to finish setting up the integration, in Encord.

## 6. Test Your Integration

Click the **Run a test** button on the integration, to test that the integration works.

<div>
  <img />
</div>

Paste the URL of any object in your Azure storage and click **Check Encord can access this URL**. If the test is successful a green tick appears next to *Encord infrastructure* and *This machine*.

<div>
  <img />
</div>

***

## Updating Expired Account-Level SAS Tokens

<Note>This section is only applicable if you used an [account-level shared access token](#method-1-generate-an-account-level-sas) to authenticate.</Note>

Shared access tokens expire and have to be updated in order to continue providing Encord with access to your Azure storage.

To update the account-level SAS token:

1. Click the three dots icon on your Azure integration.

2. Click **Update SAS token**.

A field for your new SAS token appears.

<div>
  <img />
</div>

3. In [Azure](https://portal.azure.com/#home), navigate to **Storage Accounts** under *Azure services* and select the storage account you wish to update the token for.

<div>
  <img />
</div>

4. Click on **Shared access signature** in the *Security + networking* section.

<div>
  <img />
</div>

5. You must check the *Container* and *Object* checkboxes under the *Allowed resource types* heading. Ensure you add the necessary permissions:

* Read (required)
* List (required)
* Write (recommended)
* Add (recommended)
* Create (recommended)

<Note>*recommended* permissions are necessary to use some of our more advanced features such as [re-encoding data](/platform-documentation/General/general-supported-data#re-encode-videos), and [image sequences](/platform-documentation/General/general-supported-data#image-sequences). </Note>

6. Click **Generate SAS and connection string** to generate a new account-level SAS token.

<Warning>Your SAS tokens have a start and end date that can be adjusted, and are only be valid for the specified time period. Expired tokens must be [updated](#updating-expired-account-level-sas-tokens).</Warning>

<Tip>To avoid having to update the token frequently, set the expiration date to be more than one year.</Tip>

7. Paste the new SAS token, in Encord.

***

## Azure using Workload Identity Federation

### STEP 1: In Azure

1. Create an app registration (no client secret required).

2. Add a Federated Identity Credential with scenario Other issuer:

   * **Issuer:** `https://api.encord.com/v2/public/organisation/{org_id}/serviceintegrations`
   * **Subject identifier:** `service-integration:{service_integration_uuid}`
   * **Audience:** `api://AzureADTokenExchange`

   <Note>The exact  and  are shown in the Encord setup UI.</Note>

3. Grant RBAC on the specific storage account. For example: Storage Blob Data Reader on the account, or a
   specific container.

4. Send Encord three non-secret strings: `tenant_id`, `account_name`, `client_app_id`.

5. Record the app registration's Application (client) ID.

### STEP 2: In Encord

1. Encord-org admin creates a service integration in the Encord UI and specifies `ES256` as the algorithm. This is what
   Microsoft Entra accepts.

2. Encord-org admin creates an `Azure` cloud integration with the service-integration `UUID`, `tenant id`,
   `account name`, and the client app id supplied above.

3. Test the connectivity of Encord to your storage bucket. The first connectivity test signs an assertion JWT, exchanges it for an Azure access token, and lists the configured
   container as a smoke test.

<Note>No secret is exchanged in either direction.</Note>


# Cloudflare
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-cloudflare-integration



The following steps outline how to create an Cloudflare integration in Encord.

## 1. Configure Cloudflare

1. Log into Cloudflare.

   The Cloudflare dashboard appears.

2. Click the account where your bucket is located.

   The *Account home* page appears.

3. Click **R2 object storage** from the left hand navigation.

   The *Overview R2 Object Storage* page appears.

   ![R2 object storage](https://storage.googleapis.com/docs-media.encord.com/static/img/integration-cloudflare-01.png)

4. Click **Manage**.

   The *API tokens* page appears.

   ![Create API token](https://storage.googleapis.com/docs-media.encord.com/static/img/inetgration-cloudflare-02.png)

5. Click **Create Account API token** or **Create User API token** depending on your Cloudflare account privileges.

   The *Create User API Token* page appears.

   ![Create API token](https://storage.googleapis.com/docs-media.encord.com/static/img/integration-cloudflare-03.png)

6. Specify permissions on one or more storage buckets:

   * **Permissions:**
     * For functionality: Select **Object Read & Write**
     * For limited functionality: Select **Object Read only**

   * **Buckets**
     * For simplicity: Select **Apply to all buckets in this account**
     * For Security: Select **Apply to specific buckets only**

7. Click **Create Account/User API token**.

   The *Summary* page for the API token appears.

8. Record the `Access Key ID` and `Secret Access Key`.

   ![Create API token](https://storage.googleapis.com/docs-media.encord.com/static/img/integration-cloudflare-04.png)

9. Click **Finish**.

10. Return to the *R2 object storage Overview* page.

![Record Account ID](https://storage.googleapis.com/docs-media.encord.com/static/img/integration-cloudflare-05a.png)

11. Record the `Account ID`.

12. (OPTIONAL: CORS Policy) Click the bucket the API token is applied to.

    The *Objects* page for the bucket appears.

    ![Objects page](https://storage.googleapis.com/docs-media.encord.com/static/img/integrations-cloudflare-06.png)

13. Click **Settings**.

    The *Settings* page for the bucket appears.

    ![Settings page](https://storage.googleapis.com/docs-media.encord.com/static/img/integrations-cloudflare-07.png)

14. Click **CORS Policy**.

    The *Settings* page moves to the *CORS Policy* section.

    <Warning>
      Applying Encord required CORS settings may overwrite existing configurations on your cloud storage bucket. If your bucket already has CORS settings, make sure to append Encord’s required settings instead of replacing them.
    </Warning>

15. Click **+ Add**.

    The *CORS Policy* panel appears.

    ![CORS Policy panel](https://storage.googleapis.com/docs-media.encord.com/static/img/integrations-cloudflare-08.png)

16. Copy the following into the workspace:

<CodeGroup>
  ```json Global theme={"dark"}
  [
      {
          "AllowedHeaders": [
              "*"
          ],
          "AllowedMethods": [
              "GET",
              "HEAD"
          ],
          "AllowedOrigins": [
              "https://app.encord.com",
              "https://api.encord.com",
              "https://api.us.encord.com",
              "https://app.us.encord.com"
          ],
          "ExposeHeaders": [
              "Content-Length",
              "Content-Range",
              "Accept-Ranges",
              "ETag",
              "Content-Type",
              "Last-Modified"
          ],
          "MaxAgeSeconds": 3600
      }
  ]
  ```

  ```json EU theme={"dark"}
  [
      {
          "AllowedHeaders": [
              "*"
          ],
          "AllowedMethods": [
              "GET",
              "HEAD"
          ],
          "AllowedOrigins": [
              "https://app.encord.com",
              "https://api.encord.com"
          ],
          "ExposeHeaders": [
              "Content-Length",
              "Content-Range",
              "Accept-Ranges",
              "ETag",
              "Content-Type",
              "Last-Modified"
          ],
          "MaxAgeSeconds": 3600
      }
  ]
  ```

  ```json US theme={"dark"}
  [
      {
          "AllowedHeaders": [
              "*"
          ],
          "AllowedMethods": [
              "GET",
              "HEAD"
          ],
          "AllowedOrigins": [
              "https://api.us.encord.com",
              "https://app.us.encord.com"
          ],
          "ExposeHeaders": [
              "Content-Length",
              "Content-Range",
              "Accept-Ranges",
              "ETag",
              "Content-Type",
              "Last-Modified"
          ],
          "MaxAgeSeconds": 3600
      }
  ]
  ```
</CodeGroup>

<Note>
  These rules allow byte-range requests (`GET`/`HEAD`) and expose the range and caching headers — `Content-Range`, `Content-Length`, `Accept-Ranges`, `ETag`, `Content-Type`, `Last-Modified` — that large scene files (such as MCAP) need in order to stream in chunks directly in the browser. Without them, Scenes stay stuck on *"Loading content…"* and report that the scene has no images.
</Note>

16. Click **Save**.

You are now ready to proceed to *STEP 2: Encord Configuration*.

## 2. Encord Configuration

1. Navigate to [Workspace Settings](/platform-documentation/General/general-workspace-settings#workspace-settings) > Cloud Buckets and click **+New integration** to create a new integration.

   The integration dialog appears.

2. Select *Cloudflare* in the integration dialog.

   ![New Integration](https://storage.googleapis.com/docs-media.encord.com/static/img/integrations/Cloudflare/integrations-cf-encord-step-01.png)

3. Provide a meaningful name for the integration.

   ![Cloudflare integration](https://storage.googleapis.com/docs-media.encord.com/static/img/integrations/Cloudflare/integrations-cf-encord-step-02.png)

4. Paste the following, from Cloudflare, into step 3:

   * `Account ID`
   * `Access Key ID`
   * `Secret Access Key`

   ![Cloudflare keys and ID](https://storage.googleapis.com/docs-media.encord.com/static/img/integrations/Cloudflare/integrations-cf-encord-step-03.png)

5. Specify **Advanced settings** for tighter security if required.

   ![Advanced settings](https://storage.googleapis.com/docs-media.encord.com/static/img/integrations/Cloudflare/integrations-cf-encord-step-04.png)

6. Click **Create**.

   The integration appears in the *Integrations* list.

   ![Create](https://storage.googleapis.com/docs-media.encord.com/static/img/integrations/Cloudflare/integrations-cf-encord-step-05.png)


# CoreWeave
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-coreweave-integration



The following steps outline how to create a CoreWeave integration in Encord.

## Step 1: Create a Bucket in CoreWeave

1. Log in to the [CoreWeave Console](https://console.coreweave.com/login).

2. Navigate to **Object Storage** > **Buckets**.

3. Click **Create Bucket**.

4. Provide a unique bucket name.

5. Select the zone/region for your bucket (for example, `us-east-1`).

6. Click **Create** to finalize the bucket.

<Note>
  You need the bucket url and zone, but they can be accessed later.
</Note>

## Step 2: Create an Access Key in CoreWeave

1. Go to **Object Storage** > **Keys** in the CoreWeave Console.

2. Click **Create Access Key**.

<div>
  <img />
</div>

3. Copy the *Access Key ID* and *Secret Access Key*. They are required for your integration with Encord.

<Warning>
  Store the *Secret Access Key* securely, as CoreWeave does not display it again.
</Warning>

## Step 3: Ensure the Key Has the Right Permissions

1. Go to **Object Storage** > **Organization Policies**, in the CoreWeave Console
2. Click **Create Policy**.
3. Specify the following for the policy:
   * Choose the principal associated with the Access Key.
   * 'Actions': Select `s3:GetObject`.
   * 'Resources': Select the object you just made for Encord to use.

<div>
  <img />
</div>

<Note>
  Bucket policies cannot be applied using the GUI. You can apply this policy using the S3 API or SDK. You can apply organization policies in the org which may be sufficient depending on your existing policies. Read about CoreWeave’s policies in their [documentation](https://docs.coreweave.com/docs/products/storage/object-storage/auth-access/policies).
</Note>

## Step 4: Set Up the Integration

1. Navigate to [Workspace Settings](/platform-documentation/General/general-workspace-settings#workspace-settings) > Cloud Buckets and click **+New integration**.

<div>
  <img />
</div>

2. Select **CoreWeave**.

<div>
  <img />
</div>

3. Give your integration a meaningful name.

4. Enter CoreWeave Credentials.

<Info>
  * The Access key can be found in the **Keys** tab under **Object Storage** in CoreWeave.
  * The url and zone can be found in the **Buckets** tab under **Object Storage** in CoreWeave.
</Info>

<div>
  <img />
</div>

5. Click **Create**.

<Tip>
  Test the connection to verify your integration works as expected.
</Tip>

## Step 5: Test the Integration

Click the **Run a test** button on the integration. The following errors can appear:

| Error             | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| Connection failed | Verify your Access Key, Secret Key, Bucket Name, and Endpoint URL are correct. |
| Permission denied | Ensure the Access Key has `s3:GetObject` permissions.                          |
| Region errors     | Make sure the endpoint matches the bucket region.                              |


# Direct Access
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-direct-access-integration



Direct access integrations let you register data in Encord without requiring Encord to sign your URLs. However, this means you must supply your own direct, pre-signed URLs.

<Tip>
  Alternatively, you can use unsigned URLs, but that requires a custom setup and additional Terraform code.
</Tip>

Direct access integrations support all data modalities.

<Note>Direct Access integrations are often paired with [*Strict client-only access*](/platform-documentation/General/annotate-data-integrations#strict-client-only-access) for enhanced security when supplying private cloud data. This combination ensures the highest level of data protection: *Strict client-only access* prevents Encord from accessing your data, while Direct Access keeps Encord from signing the URLs, maintaining your data's confidentiality. However, when *Strict client-only access* in enabled, all features relying on data conversion cannot be used.</Note>

<Warning>Direct access integrations cannot be used to access data with cloud provider user-based access controls.</Warning>

## Use cases

1. Public Dataset Aggregation: Researchers or analysts may need to aggregate public datasets from various sources for analysis or modeling purposes. Direct access integrations allow them to seamlessly gather data from publicly accessible sources without the need for authentication, simplifying the data acquisition process.

2. Third-Party Data Integration: Businesses often rely on third-party data providers for enriching their datasets or enhancing analytical insights. With direct access integrations, organizations can easily incorporate data from external sources by providing pre-signed URLs, streamlining the integration process and enabling timely access to valuable data.

3. Private Data Access: Workspaces may have proprietary datasets stored in private cloud environments with restricted access controls, such as IP allowlists. Direct access integrations with [*Strict client-only access*](/platform-documentation/General/annotate-data-integrations#strict-client-only-access) enable authorized users to directly upload and access this data in Encord without compromising security or violating access policies.

4. Data protection: Direct access paired with [*Strict client-only access*](/platform-documentation/General/annotate-data-integrations#strict-client-only-access) ensures compliance with stringent security requirements and regulatory standards, at the expense of some of Encord's more advanced features.

## Set Up Direct Access Integration

### Create the Integration

1. Click **Add integration**, in the *Integrations* section, to create a new integration.

<div>
  <img />
</div>

2. Select **Direct Access** from the list of possible integration types.

3. Click **Create**.

<div>
  <img />
</div>

### Set Up CORS

You must configure CORS on your storage bucket using your cloud provider’s console. For example:

* Allow the Encord application and API origins for your region.

* Allow the `GET` and `HEAD` methods.

* Allow the `If-Modified-Since`, `If-None-Match`, `If-Range`, and `Range` request headers.

* Expose the `Accept-Ranges`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, and `Last-Modified` response headers.

* [CORS configuration for AWS S3](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration#3-allow-cross-origin-resource-sharing-cors)

* [CORS configuration for Azure](/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration#3-creating-a-cors-configuration-in-azure)

* [CORS configuration for GCP Storage](/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration#creating-a-cors-configuration)

* [CORS configuration for OTC](/platform-documentation/General/annotate-data-integrations/annotate-otc-integration#3-optional-configuring-cors)

## Upload Direct Access Data

<Steps>
  <Step title="Create a Direct Access Integration">
    [Create a Direct Access integration](/platform-documentation/General/annotate-data-integrations/annotate-direct-access-integration#creating-a-direct-access-integration).
  </Step>

  <Step title="Create a JSON File for Data Registration">
    Create a JSON file to specify the files you want to register with Encord. The `objectURL`s in the JSON file must be pre-signed.

    <Note>When a Direct Access integration is used with *Strict client-only access*, the JSON file must include metadata that specifies file information for each URL. If [audioMetadata](/platform-documentation/General/annotate-data-integrations#audio-metadata), [imageMetadata](/platform-documentation/General/annotate-data-integrations#image-metadata), or [videoMetadata](/platform-documentation/General/annotate-data-integrations#video-metadata) flags are present in the JSON file, the system relies solely on the provided metadata without additional validation and does not store the file on our servers. **Ensuring the accuracy of the provided metadata is essential.**.</Note>

    <CodeGroup>
      ```json Images theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/image_file_001.jpg",
            "title": "my-custom-image-file-001.jpg",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            },
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/image_file_002.jpg",
            "title": "my-custom-image-file-002.jpg",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            },
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Audio theme={"dark"}
      {
        "audio": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file_001.mp3",
            "title": "my-custom-audio-file-001.mp3",
            "audioMetadata": {
              "duration": 23.02,
              "file_size": 2900000,
              "mime_type": "audio/mp3",
              "sample_rate": 44100,
              "bit_depth": 24,
              "codec": "mp3",
              "num_channels": 2
              },
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file_002.mp3",
            "title": "my-custom-audio-file-002.mp3",
            "audioMetadata": {
              "duration": 21.99,
              "file_size": 2900000,
              "mime_type": "audio/mp3",
              "sample_rate": 44100,
              "bit_depth": 24,
              "codec": "mp3",
              "num_channels": 2
              },
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Videos theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/video_file_001.mp4",
            "title": "my-custom-video-file-001.mp4",
            "videoMetadata": {
                "fps": 23.98,
                "duration": 29.09,
                "width": 1280,
                "height": 720,
                "file_size": 5468354,
                "mime_type": "video/mp4"
              },
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/video_file_002.mp4",
            "title": "my-custom-video-file-002.mp4",
            "videoMetadata": {
                "fps": 23.98,
                "duration": 29.09,
                "width": 1280,
                "height": 720,
                "file_size": 5468354,
                "mime_type": "video/mp4"
              },
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Text theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text-files/text_file_004.txt",
            "title": "my-custom-text-004.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "application/xml"
            }
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json PDF theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/doc-files/beowulf.pdf",
            "pdfMetadata": {
              "fileSize": 900,
              "numPages": 42
            }
          },
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Import your Direct Access Data">
    <AccordionGroup>
      <Accordion title="Register data in the UI">
        <Tip>To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our [limits and best practices for data import/registration](/platform-documentation/General/best-practices#import-into-encord) before adding data to Encord. </Tip>

        1. Navigate to **Data** > **Files & Folders** in the Encord platform.
        2. Click into a Folder.
        3. Click **+ Upload files**.
           A dialog appears.

        <div>
          <img />
        </div>

        4. Click **Import from cloud data**.

        <div>
          <img />
        </div>

        <Tip>We recommend turning on the **Ignore individual file errors** feature. This ensures that individual file errors do not lead to the whole upload process being aborted. </Tip>

        6. Click **Add JSON or CSV files** to add a [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) or [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format) file specifying cloud data that is to be added.
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="Register data using the SDK">
        To use your data in Encord, it must be uploaded to the Encord **Files & Folders** storage. Once uploaded, your data can be reused across multiple Projects and contain no labels or annotations themselves. **Files & Folders** stores your data, while *Projects* store your labels. The following script creates a folder in **Files & Folders** and uses your AWS integration to register data in that folder.

        The following script creates a new folder in **Files & Folders** and initiates uploads from AWS. It works for all file types.

        <Tip>If `Upload is still in progress, try again later!` is returned, use the
        [script to check the upload status](/sdk-documentation/getting-started-sdk/sdk-register-data-aws#step-5-check-data-upload) to see whether the upload has finished.</Tip>

        Ensure that you:

        * Replace `<private_key_path>` with the path to your private key.
        * Replace `<integration_title>` with the title of the integration you want to use.
        * Replace `<folder_name>` with the folder name. The scripts assume that the specified folder name is unique.
        * Replace `path/to/json/file.json` with the path to a [JSON file specifying which cloud storage files should be uploaded](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).
        * Replace `A folder to store my files` with a meaningful description for your folder.
        * Replace `"my": "folder_metadata"` with any metadata you want to add to the folder.

        The script has several possible outputs:

        * "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.
        * "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.
        * "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

        <CodeGroup>
          ```python Create folder and register cloud data theme={"dark"}

          # Import dependencies
          from encord import EncordUserClient
          from encord.orm.dataset import LongPollingStatus  # Ensure correct import path

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

          # Specify the integration you want to use
          integrations = user_client.get_cloud_integrations()
          integration_idx = [i.title for i in integrations].index("<integration_title>")
          integration = integrations[integration_idx].id

          # Create a storage 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
          )

          # Initiate cloud data registration
          upload_job_id = storage_folder.add_private_data_to_folder_start(
              integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
          )

          # Check upload status
          res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
          print(f"Execution result: {res}")

          if res.status == LongPollingStatus.PENDING:
              print("Upload is still in progress, try again later!")
          elif res.status == LongPollingStatus.DONE:
              print("Upload completed")
              if res.unit_errors:
                  print("The following URLs failed to upload:")
                  for e in res.unit_errors:
                      print(e.object_urls)
          else:
              print(f"Upload failed: {res.errors}")

          ```

          ```Example output theme={"dark"}
          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.
          ```
        </CodeGroup>
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## Direct Access with Unsigned URLs

You can configure secure data access with unsigned URLs using a Terraform setup **In GCP**.

<Note>
  The following section is intended for users who are familiar with Terraform.
</Note>

1. Connect to a static IP (for example a VPN).
2. In the terraform code, sett all the following variables.

* `<DNS_MAPPING_DOMAIN_NAME>`
* `<DNS_MANAGED_ZONE_NAME>`
* `<BUCKET_NAME>`
* `<GCP_PROJECT_ID>`
* `<BUCKET_REGION>`

3. In the terraform code, add the IP addresses that should be allowed to access your data.
4. Optionally, if you want to use an existing bucket rather create a new one you must adjust the terraform code.
5. Apply the Terraform configuration.
6. Ensure your [upload JSON](#upload-direct-access-data) uses the `DNS_MAPPING_DOMAIN_NAME` defined in your terraform code instead of the public URL (`https://storage.googleapis.com`).

<Note>
  If you update your Cloud Armor configuration — such as adding or removing allowed IP addresses — you must invalidate the CDN cache for the changes to take effect immediately. Otherwise, the updates only apply once the existing cache expires (currently set to 1 hour).

  You can learn how to invalidate cached content in the [Google Cloud documentation](https://docs.cloud.google.com/cdn/docs/invalidating-cached-content)
</Note>

<Tabs>
  <Tab title="Connectivity Diagram">
    <div>
      <img />
    </div>
  </Tab>

  <Tab title="Terraform Code">
    <CodeGroup>
      ```edge Boilerplate theme={"dark"}
      locals {
      domain       = "<DNS_MAPPING_DOMAIN_NAME>" # replace with your domain name
      managed_zone = "<DNS_MANAGED_ZONE_NAME>"  # replace with your managed DNS - this is only required if you want to create a DNS record.
      bucket_name  = "<BUCKET_NAME>" # replace with your desired bucket name (new bucket is created)
      project_id   = "<GCP_PROJECT_ID>" # replace with your GCP project ID
      bucket_region = "<BUCKET_REGION>" # replace with your bucket's region. Used to create multi-region bucket.

      # List of allowed IPs to access the bucket via the load balancer
      allowed_ips = [
        "22.22.22.22/32", # Replace with the IPs you want to grant access
        #"11.11.11.11/32",
        #"xxx.xx.xx.xx/32", 
      ]
      }
      terraform {
      required_providers {
        google = {
          source = "hashicorp/google"
          version = "7.11.0"
        }
      }
      }
      provider "google" {
      project = local.project_id
      }
      # Private GCS bucket
      resource "google_storage_bucket" "cdn_bucket" {
      name          = local.bucket_name
      location      = local.bucket_region
      storage_class = "MULTI_REGIONAL"
      force_destroy = false
      uniform_bucket_level_access = true
      public_access_prevention    = "enforced"
      versioning {
        enabled = false
      }
      }
      # IP and certificate (will take minutes to hours to provision)
      resource "google_compute_global_address" "cdn_ip" {
      name         = "cdn-ip"
      ip_version   = "IPV4"
      address_type = "EXTERNAL"
      }
      resource "google_dns_record_set" "cdn_dns_record" {
      name         = "${local.domain}."
      managed_zone = local.managed_zone
      rrdatas      = [
        google_compute_global_address.cdn_ip.address
      ]
      ttl          = 300
      type         = "A"
      }
      resource "google_compute_managed_ssl_certificate" "cdn_certificate" {
      name = "cdn-certificate"
      managed {
        domains = [
          local.domain,
        ]
      }
      }
      # Cloud Armor Security Policy
      resource "google_compute_security_policy" "cdn_security_policy" {
      name        = "cdn-security-policy"
      description = "Security policy to restrict access to specific IPs"
      # Default rule - deny all
      rule {
        action   = "deny(403)"
        priority = "2147483647"
        match {
          versioned_expr = "SRC_IPS_V1"
          config {
            src_ip_ranges = ["*"]
          }
        }
        description = "Default deny all rule"
      }
      # Allow specific IPs
      rule {
        action   = "allow"
        priority = "1000"
        match {
          versioned_expr = "SRC_IPS_V1"
          config {
            src_ip_ranges = local.allowed_ips
          }
        }
        description = "Allow traffic from specific IPs"
      }
      }
      # Load Balancer
      resource "google_compute_global_network_endpoint_group" "cdn_network_endpoint_group" {
      name                  = "cdn-network-endpoint-group"
      network_endpoint_type = "INTERNET_FQDN_PORT"
      default_port          = 443
      }
      resource "google_compute_global_network_endpoint" "cdn_network_endpoint" {
      global_network_endpoint_group = google_compute_global_network_endpoint_group.cdn_network_endpoint_group.id
      fqdn                          = "${google_storage_bucket.cdn_bucket.name}.storage.googleapis.com"
      port                          = google_compute_global_network_endpoint_group.cdn_network_endpoint_group.default_port
      }
      resource "google_compute_backend_service" "cdn_backend_service" {
      name                  = "cdn-backend-service"
      description           = "Backend service for Google Cloud CDN"
      load_balancing_scheme = "EXTERNAL_MANAGED"
      compression_mode      = "AUTOMATIC"
      protocol              = "HTTPS"
      enable_cdn            = true
      security_policy       = google_compute_security_policy.cdn_security_policy.id
      backend {
        group = google_compute_global_network_endpoint_group.cdn_network_endpoint_group.id
      }
      custom_request_headers = [
        "Host:${google_storage_bucket.cdn_bucket.name}.storage.googleapis.com",
        "Cookie:", # unset cookies to avoid HMAC authentication failure
      ]
      custom_response_headers = [
        "X-Cache-Hit:{cdn_cache_status}"
      ]
      cdn_policy {
        cache_mode       = "FORCE_CACHE_ALL"
        negative_caching = false
        cache_key_policy {
          include_host         = true
          include_query_string = true
        }
        bypass_cache_on_request_headers {
          header_name = "X-Bypass-Cache"
        }
      }
      security_settings {
        aws_v4_authentication {
          access_key_id = google_storage_hmac_key.cdn_hmac_key.access_id
          access_key    = google_storage_hmac_key.cdn_hmac_key.secret
          origin_region = "europe-west1"
        }
      }
      }
      resource "google_compute_url_map" "cdn_lb" {
      name            = "cdn-lb"
      description     = "Load Balancer to redirect requests to bucket backend"
      default_service = google_compute_backend_service.cdn_backend_service.id
      }
      resource "google_compute_target_https_proxy" "cdn_https_proxy" {
      name             = "cdn-https-proxy"
      url_map          = google_compute_url_map.cdn_lb.self_link
      ssl_certificates = [google_compute_managed_ssl_certificate.cdn_certificate.self_link]
      }
      resource "google_compute_global_forwarding_rule" "cdn_https_forwarding_rule" {
      name                  = "cdn-https-forwarding-rule"
      target                = google_compute_target_https_proxy.cdn_https_proxy.self_link
      ip_address            = google_compute_global_address.cdn_ip.address
      load_balancing_scheme = "EXTERNAL_MANAGED"
      port_range            = "443"
      }
      # Partial load balancer for https redirects
      resource "google_compute_url_map" "cdn_lb_https_redirect" {
      name        = "cdn-lb-https-redirect"
      description = "Partial Load Balancer for HTTPS Redirects"
      default_url_redirect {
        https_redirect = true
        strip_query    = false
      }
      }
      resource "google_compute_target_http_proxy" "cdn_http_proxy" {
      name    = "cdn-http-proxy"
      url_map = google_compute_url_map.cdn_lb_https_redirect.id
      }
      resource "google_compute_global_forwarding_rule" "cdn_http_forwarding_rule" {
      name                  = "cdn-http-forwarding-rule"
      target                = google_compute_target_http_proxy.cdn_http_proxy.id
      ip_address            = google_compute_global_address.cdn_ip.id
      load_balancing_scheme = "EXTERNAL_MANAGED"
      port_range            = "80"
      }
      # Service Account
      resource "google_service_account" "cdn_bucket_service_account" {
      account_id   = "cdn-service-account"
      display_name = "CDN Service Account"
      }
      resource "google_storage_bucket_iam_member" "cdn_bucket_object_reader" {
      bucket = google_storage_bucket.cdn_bucket.name
      role   = "roles/storage.legacyObjectReader"
      member = "serviceAccount:${google_service_account.cdn_bucket_service_account.email}"
      }
      resource "google_storage_hmac_key" "cdn_hmac_key" {
      service_account_email = google_service_account.cdn_bucket_service_account.email
      }
      ```

      ```edge Example Values theme={"dark"}
        locals {
        domain       = "encord-directaccess.acme.com" 
        managed_zone = "acme.com"
        bucket_name  = "encord-data" 
        project_id   = "my-gcp-project"
        bucket_region = "EU"

        # List of allowed IPs to access the bucket via the load balancer
        allowed_ips = [
          "39.42.20.11/32",
          "130.192.120.23/32",
        ]
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Upload JSON">
    The following is an example JSON to upload a PDF file, using an example `DNS_MAPPING_DOMAIN_NAME`

    ```json PDF theme={"dark"}
    {
      "pdfs": [
        {
          "objectUrl": "https://encord-directaccess.acme.com/doc-files/beowulf.pdf",
          "pdfMetadata": {
            "fileSize": 900,
            "numPages": 42
          }
        },
      ],
      "skip_duplicate_urls": true
    }
    ```
  </Tab>
</Tabs>


# GCP Storage
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration



There are multiple parts to setting up a GCP integration in Encord:

1. Start setting up the integration in Encord.
2. Grant service account access and register your storage bucket with Encord.
3. Set up a CORS configuration.

<Note>
  Ensure all objects in the bucket use the [Standard Storage class](https://cloud.google.com/storage/docs/storage-classes).
</Note>

## 1. Start Setting Up The Integration

1. Navigate to [Workspace Settings](/platform-documentation/General/general-workspace-settings#workspace-settings) > Cloud Buckets and click **+New integration**.

<div>
  <img />
</div>

2. Select **Google Cloud Storage**.

3. Give your integration a meaningful title.

<div>
  <img />
</div>

## 2. Grant Service Account Access

1. Log into your Google Cloud account and navigate to the <a href="https://console.cloud.google.com/storage/browser">GCP bucket</a> you want to integrate with Encord.

2. Click **Grant Access** to add a service account for Encord, in the bucket's **PERMISSION** tab.

3. Add `cord-cloud-storage-integrator@cord-ai-platform.iam.gserviceaccount.com` as a New Principal and assign the following roles:

* `Storage Object Viewer`
* `Storage Object Creator`

<Info>
  `Storage Object Creator` is needed for features that require write permissions, including [re-encoding data](/platform-documentation/General/general-supported-data#re-encode-videos) and creating [image sequences](/platform-documentation/General/general-supported-data#image-sequences).
</Info>

<div>
  <img />
</div>

### 2.1 Register the cloud bucket with Encord

Paste the name of your GCP bucket into Step 2.1 of the integration in Encord.

<div>
  <img />
</div>

## 3. Create a CORS Configuration

<Warning>
  If you use Infrastructure as Code tools like Terraform, they can overwrite your manual CORS settings. To prevent this, always include the correct CORS policy in your Terraform configuration file.
</Warning>

<Warning>
  Applying Encord required CORS settings may overwrite existing configurations on your cloud storage bucket. If your bucket already has CORS settings, make sure to append Encord’s required settings instead of replacing them.
</Warning>

A [CORS configuration](https://cloud.google.com/storage/docs/cors-configurations) must be applied to the bucket you want to integrate with Encord. A CORS configuration enables Encord to request resources from the specified bucket.

<Note>The only way to create a CORS configuration is using the command line or terminal tool. </Note>

[Install Google's Cloud CLI](https://cloud.google.com/sdk/docs/install-sdk), and use the following `gcloud` command in your command line or terminal to create a CORS configuration.

```
gcloud storage buckets update  gs://<YOUR_BUCKET_NAME> --cors-file="/path/to/you/cors.json"
```

* Replace \<YOUR\_BUCKET\_NAME> with the name of the bucket you want to integrate.
* Replace `/path/to/you/cors.json` with the full path to your JSON CORS file. A [sample JSON file](#json-configuration-file) is provided below.

Click **Create** in Encord to finish creating the integration, after creating a CORS configuration.

### JSON configuration file

The following JSON file can be used to set up the CORS configuration in Step 3 of your GCP integration.

<CodeGroup>
  ```json Global theme={"dark"}
  [
      {
        "origin": ["https://app.encord.com", "https://api.encord.com","https://app.us.encord.com", "https://api.us.encord.com"],
        "method": ["GET", "HEAD"],
        "responseHeader": ["If-Modified-Since", "If-None-Match", "If-Range", "Range", "Accept-Ranges", "Content-Length", "Content-Range", "Content-Type", "ETag", "Last-Modified"],
        "maxAgeSeconds": 3600
      }
  ]
  ```

  ```json EU theme={"dark"}
  [
      {
        "origin": ["https://app.encord.com", "https://api.encord.com"],
        "method": ["GET", "HEAD"],
        "responseHeader": ["If-Modified-Since", "If-None-Match", "If-Range", "Range", "Accept-Ranges", "Content-Length", "Content-Range", "Content-Type", "ETag", "Last-Modified"],
        "maxAgeSeconds": 3600
      }
  ]
  ```

  ```json US theme={"dark"}
  [
      {
        "origin": ["https://app.us.encord.com", "https://api.us.encord.com"],
        "method": ["GET", "HEAD"],
        "responseHeader": ["If-Modified-Since", "If-None-Match", "If-Range", "Range", "Accept-Ranges", "Content-Length", "Content-Range", "Content-Type", "ETag", "Last-Modified"],
        "maxAgeSeconds": 3600
      }
  ]
  ```
</CodeGroup>

<Note>
  * Preflight requests are valid for 1 hour. Use the `maxAgeSeconds` variable to adjust the number of seconds the browser is allowed to make requests before it must repeat the preflight request.
  * Successful browser requests return the `Content-Type` of the resource in the response, as set by the `responseHeader`.
  * Byte-range requests (`GET`/`HEAD`) require the `Range` request header and the exposed response headers shown above so large scene files (such as MCAP) can stream in chunks in the browser.
</Note>

Consult the [GCP documentation](https://cloud.google.com/storage/docs/cors-configurations), to customize the file further.

## 4. Test Integration

Click the **Run a test** button on the integration to test the integration.

<div>
  <img />
</div>

Paste the URL of any object in the bucket and click **Check Encord can access this URL**. If the test is successful a green tick appears next to *Encord infrastructure* and *This machine*.

<div>
  <img />
</div>

***

## Register GCP Data

See the [Register cloud data](/platform-documentation/Curate/add-files/index-register-cloud-data) page for guidance on how to register data stored in GCP.

<Tip>We recommend setting the expiration time for pre-signed URLs (found in your cloud storage settings) to be greater than the time it takes to complete an annotation task. [More information can be found in the GCP documentation](https://cloud.google.com/storage/docs/access-control/signed-urls).</Tip>


# MinIO
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-minIO-integration



In the *Integrations* section of the Encord platform, click **+New integration** to create a new integration.
The integration dialog appears.

<div>
  <img />
</div>

### Step 1: Create an IAM Policy

1. In the Encord platform click *MinIO* at the top of the integration dialog.

2. Give your integration a meaningful name.

<div>
  <img />
</div>

3. In MinIO, navigate to *Policies* and create a new policy.

<div>
  <img />
</div>

4. Click **Create policy**.

## 2. Create Users for Encord Integration Access

1. In MinIO, navigate to the *Users* section and click **Create user**.

<div>
  <img />
</div>

2. Make sure to select the *Programmatic* access type. This generates an API Access Key for the newly created user.

3. Assign the policy created in Step 1 to the user.

4. Click **Create user**.

<div>
  <img />
</div>

5. Create an *Access Key* for the account.

<div>
  <img />
</div>

6. Download the Access Key as a CSV and save it in a secure location.
   The CSV contains the *Account access key ID* and *Account secret access key*.

<div>
  <img />
</div>

## 3. Add the Access Key to Encord

1. In the Encord platform, paste the *Account access key ID* and *Account secret access key* into Step 2 of the MinIO integration window.

<div>
  <img />
</div>

2. Give the account read access to the desired buckets.

3. Set the CORS permissions of your buckets.

4. Click **Create** to create your MinIO integration.


# Oracle
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-oracle-integration



The following steps outline how to create an Oracle integration in Encord.

## 1: Create a User for Encord

1. In Oracle, navigate to *Identity* and click on *Domain*.
2. Select your domain.
3. Navigate to *Users* and click **Create user**.
   A dialog box will appear, prompting you to enter details for the new user.

<div>
  <img />
</div>

4. Fill in the details for the new user.

<div>
  <img />
</div>

## 2: Create an Access Key for the User

1. Select the user you created in Step 1.
2. Navigate to *Customer secret keys* in the left hand navigation.
3. Click **Generate secret key**.
   A dialog appears.

<div>
  <img />
</div>

4. Give your access key a meaningful name and create the access key.
   The access key and secret key are generated.

5. Click **Copy** to copy the secret key. Store it in a secure location - you will need it later.

<div>
  <img />
</div>

6. Hover over the access key, and click **Copy** to copy the access key.

<div>
  <img />
</div>

## 3: Create a Group for the User

1. In Oracle, navigate to *Identity* and click on *Domain*.

2. Select your domain.

3. Navigate to *Groups* and click **Create group**.
   A dialog box will appear, prompting you to enter details for the new group.

<div>
  <img />
</div>

4. Enter a meaningful name for the group and add the user you created in Step 1.

<div>
  <img />
</div>

## 4: Create a Policy

1. In Oracle, navigate to *Identity* and click on *Policies*.

2. Click **Create policy**.
   A dialog box will appear, prompting you to enter details for the new policy.

<div>
  <img />
</div>

3. Give the policy a meaningful name and description.

4. Enable the *Manual policy editor* toggle and paste the following into the policy editor, replacing \<ENCORD\_USER\_GROUP\_NAME> with the name of the group you created in Step 3, and replacing \<BUCKET\_NAME\_USED\_FOR\_INTEGRATION> with the name of your storage bucket.

   `Allow group <ENCORD_USER_GROUP_NAME> to read objects in TENANCY where target.bucket.name='<BUCKET_NAME_USED_FOR_INTEGRATION>'`

<div>
  <img />
</div>

## 5: Create the Integration

1. In the *Integrations* section of the Encord platform, click **+New integration** to create a new integration.
   The integration dialog appears.

<div>
  <img />
</div>

2. Select *Oracle* in the integration dialog.

3. Paste the *Account access key* and the *Account secret access key* from Step 2 into the integration dialog.

4. Enter the bucket namespace of your storage bucket into the integration dialog. The bucket namespace can be found in your bucket details in Oracle.

<div>
  <img />
</div>

5. In Encord, click **Create** to create the integration.

<div>
  <img />
</div>


# Open Telekom Cloud
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-otc-integration



In order to integrate with Open Telecom Cloud, you must:

1. Create the account to access data in the Object Storage Service.
2. Give the account read access to the desired buckets by:
   * Creating a Custom Bucket Policy.
   * (Optional) If you have *Cross-origin resource sharing (CORS)* configured on your buckets, make sure that `*.encord.com` is given read access.
3. Create the integration.

## 1. Start Setting up the Integration

1. To create an Open Telekom Cloud integration, click the **+ Add integration** button in the [Integrations tab](/platform-documentation/General/annotate-data-integrations). Select *OTC*.

<div>
  <img />
</div>

2. Give the integration a meaningful name

<div>
  <img />
</div>

## 2. Create an Account for Encord IAM

1. Log in to the OTC console and navigate to the Identity and Access Management (IAM) dashboard.

2. Create a new user with *Programmatic access*.

<img />

3. Download the access key.

<img />

4. Paste the `OTC account access ID` and the `Secret access key` into Step 2 of the OTC integration window in Encord.

<div>
  <img />
</div>

## 3. Give the Account Read Access to Your Buckets

1. In OTC, navigate to the bucket and click the **Create Bucket Policy** button.

2. Click **OK** to create the custom bucket policy.

<img />

## 4. Configuring CORS

<Warning>
  If you use Infrastructure as Code tools like Terraform, they can overwrite your manual CORS settings. To prevent this, always include the correct CORS policy in your Terraform configuration file.
</Warning>

If your bucket has a configured CORS policy, make sure it permits access from `*.encord.com`.

<img />

## 5. Create the Integration

In Encord, click the **Create** button at the bottom of the integration pop-up. The integration now appears in the list of integrations.

## 6. Testing the Integration

1. Click the **Run a test** button to test the integration.

<div>
  <img />
</div>

2. Paste the URL of any object in the bucket and click **Check Encord can access this URI**. If the test is successful a green tick appears next to *Encord infrastructure* and *This machine*.

<div>
  <img />
</div>

***

## Register OTC Data

Navigate to the [Register cloud data](/platform-documentation/Curate/add-files/index-register-cloud-data) page for guidance on how to register data stored in OTC to Encord.


# Wasabi
Source: https://docs.encord.com/platform-documentation/General/annotate-data-integrations/annotate-wasabi-integration



In the *Integrations* section of the Encord platform, click **+New integration** to create a new integration.
The integration dialog appears.

<div>
  <img />
</div>

## 1: Create an IAM Policy

1. In the Encord platform click *Wasabi* at the top of the integration dialog.

2. Give your integration a meaningful name.

3. Copy the JSON from step 1 of the integration.

<div>
  <img />
</div>

4. In Wasabi, navigate to *Policies* and create a new policy.

<div>
  <img />
</div>

5. Paste the JSON you copied from the Encord platform into the *Policy Editor*, replacing the `YourBucket` with the name of your bucket. Ensure that the Resource value ends in /\*.

<div>
  <img />
</div>

<Note>If you do not plan on using features that require write permissions, such as [re-encoding data](/platform-documentation/General/general-supported-data#re-encode-videos) and creating [image sequences](/platform-documentation/General/general-supported-data#image-sequences), `s3:PutObject` can be omitted. </Note>

6. Click **Create policy**.

## 2. Create Users for Encord Integration Access

1. In Wasabi, navigate to the *Users* section and click **Create user**.

<div>
  <img />
</div>

2. Make sure to select the *Programmatic* access type. This will generate an API Access Key for the newly created user.

3. Assign the policy created in step 1 to the user.

4. Click **Create user**.

<div>
  <img />
</div>

5. Download the Access Key as a CSV and save it in a secure location.
   The CSV contains the *Account access key ID* and *Account secret access key*.

<div>
  <img />
</div>

## 3. Add the Access Key to Encord

1. In the Encord platform, paste the *Account access key ID* and *Account secret access key* into Step 2 of the Wasabi integration window.

<div>
  <img />
</div>

2. Select the region in which you created your bucket.

3. Click **Create** to create your Wasabi integration.


# Glossary
Source: https://docs.encord.com/platform-documentation/General/annotate-glossary



We conform to industry naming standards wherever possible in a bid to make the user experience both intuitive and welcoming to new users and experienced practitioners alike. However, computer vision and annotation tooling are relatively recent fields, and as such many terms may be used interchangeably in both the literature and industry.

<Note>In the interests of brevity, we refer to both image and video data as 'frames' in the definitions below.</Note>

| **Term**                     | **Description**                                                                                                                                                                                                                                                                                                         |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Benchmark function           | The function used to review tasks with automated QA. The benchmark function works by comparing all labels in the annotator submission of the benchmark task against the gold standard label set in the source project’s task.                                                                                           |
| Benchmark task               | An annotation task in a project with automated QA, which has a corresponding task in the ‘source project’ that contains gold standard labels.                                                                                                                                                                           |
| Bounding box                 | A rectangle used to annotate a feature by drawing the bounds of the feature.                                                                                                                                                                                                                                            |
| Crosshair navigation         | A way to navigate in 3d. Clicking on a location in one slice will change also the associated views.                                                                                                                                                                                                                     |
| Data Group                   | More than one file grouped together to form a single Data Unit. For example, a Data Group could contain 4 videos and 1 text file. Data Groups support multi-modality.                                                                                                                                                   |
| Data Unit                    | A package of data that constitutes a single annotation task. For example, a video, a single image, an image group, and image sequence, a data group, a Scene, or a DICOM series.                                                                                                                                        |
| Feature                      | An object in a frame, or a classification applied to a frame. These can be used to identify something in a frame (object: 'this thing is an apple') or to classify the frame itself (classification: 'this frame has apples').                                                                                          |
| Hanging protocol             | An arrangement of views e.g. Axial, sagittal and coronal.                                                                                                                                                                                                                                                               |
| Image group                  | A collection of images of varying dimensions combined into a single data unit. Automated labeling is not supported for Image groups. Please see our documentation on Image groups in the Supported data section for more information.                                                                                   |
| Image sequence               | A collection of images with the same dimensions combined into a single data unit. Automated labeling is supported for Image sequences. Please see our documentation on Image groups in the Supported data section for more information.                                                                                 |
| Instance                     | Also known as an instance label in the platform. An instance is unique instantiation of an ontology entity, which depending on the data type, may contain many frame labels. For example, in 100 frame video tracking three cars on a road, there are three instances of 'car' and up to 100 frame labels for each car. |
| Key frame                    | Key frames or `keyframes` are frames of interest in videos. You can specify key frames during or after storage item imports. Specifying key frames speeds import to Active and Index and helps you focus on only the frames you deem important.                                                                         |
| Label Editor                 | The UI for annotating data and managing labels.                                                                                                                                                                                                                                                                         |
| Label                        | Used interchangeably with 'annotation', and sometimes denoted as a frame label in the platform. Labels note relevant features in a frame and apply to a dataset used in model training. They are an annotation asserting which features in the desired ontology are true.                                               |
| Maximum intensity projection | A method for 3d data that projects all voxels to a plane.                                                                                                                                                                                                                                                               |
| model                        | A model specifically trained to label particular features in datasets - which are then used to train production models.                                                                                                                                                                                                 |
| Production model             | A program with a set of functions and parameters that allow it to recognize features in datasets. Production models are the end use-case of labeled data.                                                                                                                                                               |
| Model training               | The process of teaching a model an ontology. This is done by algorithmically changing model parameters until it can reliably recognize features that are labeled in a dataset.                                                                                                                                          |
| Model inference              | The process of using a trained model to predict the presence of features in new data.                                                                                                                                                                                                                                   |
| Object detection             | The ability of a model to reliably recognize when a frame contains an object of interest. An application of model inference.                                                                                                                                                                                            |
| Object primitive             | A unique object annotation type. Used to create templates of shapes (such as 3D cuboids and pose estimation skeletons) commonly used by your annotation team.                                                                                                                                                           |
| Object tracking              | An automated labeling feature designed to track objects in a sequence of frames over time. It is not an application of models and distinct from Object detection. Please see our documentation on Object tracking for more information.                                                                                 |
| Ontology                     | A defined set of features and their relationships. This is what a model will be trained to apply to frames. Also known as a 'taxonomy' or 'labeling protocol'.                                                                                                                                                          |
| Polygon                      | A polygonal shape used to annotate a feature by drawing the feature's boundary.                                                                                                                                                                                                                                         |
| Polyline                     | A line composed of multiple segments.                                                                                                                                                                                                                                                                                   |
| Scene                        | A Scene consists of a single point cloud file or a point cloud file with one or more videos.                                                                                                                                                                                                                            |
| Semantic segmentation        | The application of labels to each pixel in a frame in order to classify segments of the frame as part of the same entity.                                                                                                                                                                                               |
| Slice                        | A single image of a dicom volume.                                                                                                                                                                                                                                                                                       |
| View                         | Window displaying a specific viewing direction e.g. coronal.                                                                                                                                                                                                                                                            |
| Volume                       | A set of images, also called slices or frames.                                                                                                                                                                                                                                                                          |
| Windowing                    | Changing the appearance of the image to highlight particular structures.                                                                                                                                                                                                                                                |
| Confidence score             | The confidence score is a measure of a machine learning model's certainty that a given prediction is accurate. The higher the confidence score, the more certain a model is about its prediction.                                                                                                                       |
| Intensity value              | Intensity values represent the densities of the scanned object. Standardized values for CT scans are referred to as Hounsfield units.                                                                                                                                                                                   |
| Router                       | A router is a workflow project component that splits the path that annotation or review tasks take through a workflow.                                                                                                                                                                                                  |
| Object                       | Something of interest in a frame. Defined by string together with an annotation. It can be used as part of an ontology to label entities of interest in a dataset used for model training. Examples include Bounding boxes and polygons that have been applied to a frame.                                              |
| Keypoint                     | A geometric point useful for tracking small objects or particular points of interest on larger objects.                                                                                                                                                                                                                 |
| Bitmask                      | Bitmasks are binary masks applied to images, where pixels are either shown or hidden. In Encord we use a brush tool to create bitmasks.                                                                                                                                                                                 |
| Classification               | A mutually-exclusive category applied to a frame.                                                                                                                                                                                                                                                                       |
| Attribute                    | Attributes can be nested into objects to provide more information on the label. For an the object 'cat' an example attribute would be 'color'.                                                                                                                                                                          |
| Label Row                    | A collection of labels belonging to a particular data unit in a Project.                                                                                                                                                                                                                                                |
| Foundation model             | A large-scale, pretrained neural network trained on massive datasets, designed to serve as a base for various downstream tasks. These models can be fine-tuned for specific applications such as natural language understanding or image generation.                                                                    |
| LLM / VLM                    | **LLM (Large Language Model):** A model designed for processing and generating human-like text, trained on vast amounts of textual data. **VLM (Vision-Language Model):** A model capable of understanding and generating outputs across both text and visual modalities.                                               |
| Multimodal                   | Refers to systems or models capable of processing and integrating information from multiple data modalities, such as text, images, audio, or video.                                                                                                                                                                     |
| Fine-Tuning (IFT/SFT)        | **Instruction Fine-Tuning (IFT):** Adjusting a pretrained model to perform specific tasks by training it on examples with explicit instructions. **Supervised Fine-Tuning (SFT):** Refining a model using a labeled dataset for a specialized task.                                                                     |
| RLHF                         | Reinforcement Learning from Human Feedback: A training technique where human preferences guide the model's learning process to align its outputs with desired behaviors.                                                                                                                                                |
| Benchmark                    | A standardized dataset or evaluation process used to measure and compare the performance of machine learning models, often serving as a baseline for progress in specific tasks or domains.                                                                                                                             |
| Agent                        | An autonomous system or model capable of making decisions and taking actions to achieve specific goals, often using reinforcement learning or other techniques to interact with and learn from environments.                                                                                                            |
| Data Governance / Provenance | **Data Governance:** Policies and practices ensuring data quality, security, and ethical use throughout its lifecycle. **Data Provenance:** Documentation and tracking of data origin, history, and transformations for transparency and accountability.                                                                |


# Best Practices
Source: https://docs.encord.com/platform-documentation/General/best-practices



## Guidelines for Optimal Performance

While the Encord platform is able to handle large volumes of data, we strongly recommend working within the following limits to ensure smooth operations and limit loading times.

<Note>The limits outlined below apply for both the SDK, and the Encord platform.</Note>

### Get Help

As you explore the Encord platform, you may have questions about specific features or use cases. To assist you, Encord offers an AI documentation assistant designed to provide quick, accurate answers.

1. Click **Help** in the top-right corner of the Encord platform.
2. Select the **Ask AI** button to access the Encord documentation AI.
3. Type your question in natural language, and the AI will provide the information you need.

![AI Help widget](https://storage.googleapis.com/docs-media.encord.com/static/img/help-ai-widget-app.png)

You can close the AI Help widget at anytime if you feel it is in your way.

***

### Import Into Encord

The following recommendations apply to the Encord platform and the SDK.

<Tip>We recommend uploading files in batches not exceeding 2GB, to ensure upload does not exceed 3 hours.</Tip>

<Tip> Image groups upload faster than image sequences. </Tip>

<Info>
  Encord enforces the following upload limits for each [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) used for registering files:

  * Up to 1 million URLs
  * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  * URLs can be up to 16 KB in size

  Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller registrations and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
</Info>

Before registering your data think about how you want to search for and filter your data. [Custom metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata) can always be added to your data after your initial data registration or import, but starting with a strong foundation of custom metadata (by importing it while registering your data) can significantly decrease the time to ROI and achieving your goals.

| **Limit**                           | **Enterprise**           | **Team**                |
| ----------------------------------- | ------------------------ | ----------------------- |
| Maximum # of data units at one time | 10,000                   | 2,500                   |
| Maximum image/video/DICOM file size | 1 GB                     | 1 GB                    |
| Maximum JSON file size              | 100 MB or 10,000 entries | 100 MB  or 2500 entries |
| Label row / Annotation task limit\* | 50 MB                    | 50 MB                   |
| Model predictions import limit      | 50 MB                    | 50 MB                   |
| Maximum resolution                  | 4K (3840 x 2160 px)      | 4K (3840 x 2160 px)     |
| Number of frames per video          | 200,000 (2hrs at 30fps)  | 200,000 (2hrs at 30fps) |

<Info>
  \* Label row / Annotation task size limit: As a practical guideline, 50 MB typically supports up to \~30 minutes of labelled content in 30fps video with \~20 annotations per frame.
</Info>

<Note>
  Active supports analysis (Advanced Metrics and Embeddings) on images and videos up to 4K resolution. Performance is affected for images and videos over 4K.

  For optimal performance, we strongly recommend downscaling images and videos over 4K to 4K resolution.
</Note>

When a Project is too large, the files in the attached Dataset(s) must be resized.

<div>
  <img />
</div>

<Tip>Learn how to [resize your videos here](/platform-documentation/General/general-supported-data#resizing-videos).</Tip>

***

### Annotate Projects

<div>
  | **Limit**                                          | **Enterprise** | **Team**  |
  | -------------------------------------------------- | -------------- | --------- |
  | Maximum number of Projects                         | Unlimited      | Unlimited |
  | Maximum dataset size per Project                   | 100 GB         | 100 GB    |
  | Maximum number of labels per Project \*            | 5,000,000      | 1,000,000 |
  | Maximum number of instances per *Workflow* Project | 500,000        | 500,000   |
  | Maximum number of tasks per *Workflow* Project     | 500,000        | 500,000   |
</div>

\* labels = number of instances multiplied by the number of frames they are present in. Labels often accumulate in long videos or large images with many separate objects.

<Tip> If the number of labels in your Project exceeds our specified limits, consult us.</Tip>

***

### Label Editor Rendering

For optimal labeling performance while labeling, refer to the table below for our recommendations for each modality.

<Note>
  Performance varies depending on the specification of your computer/laptop/tablet.
</Note>

<table>
  <thead>
    <tr>
      <th>Modality</th>
      <th>Capability</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Image</td>
      <td>300 labels per image</td>
    </tr>

    <tr>
      <td>Video</td>
      <td>Coming soon</td>
    </tr>

    <tr>
      <td>Audio file</td>
      <td>Coming soon</td>
    </tr>

    <tr>
      <td>Text file</td>
      <td>Coming soon</td>
    </tr>

    <tr>
      <td>HTML file</td>
      <td>Coming soon</td>
    </tr>

    <tr>
      <td>PDF</td>
      <td>Coming soon</td>
    </tr>

    <tr>
      <td>DICOM file</td>
      <td>Coming soon</td>
    </tr>

    <tr>
      <td>NIfTI file</td>
      <td>Coming soon</td>
    </tr>

    <tr>
      <td>Lidar file</td>
      <td>Coming soon</td>
    </tr>
  </tbody>
</table>

### Cloud Synced Folders

[Cloud synced folders](/platform-documentation/Curate/add-files/index-register-cloud-data-cloud-sync) can contain a maximum of 10 million files

***

### Custom Metadata and Embeddings support

Active, Index, and to a degree Annotate, support custom metadata.

Index supports custom embeddings.

Active supports custom embeddings on data (images, image groups, image sequences, videos) and supports calculating embeddings using a generalized method for both data (images, image groups, image sequences, videos) and on labels and predictions (bitmasks, bounding boxes, rotatable bounding boxes, polygons).

<table>
  <thead>
    <tr>
      <th>Feature</th>
      <th>Index</th>
      <th>Annotate</th>
      <th>Active</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Custom Metadata</td>
      <td>Supports numerical, time date (filtering and analytics), varchar, text, enum and options, key frames</td>
      <td>Supports custom layouts for Label Editor.</td>
      <td>Supports numerical, time date (filtering), varchar, text, enum and options, key frames</td>
    </tr>

    <tr>
      <td>Custom Embeddings</td>
      <td>Supports 1 to 4096 embeddings on images, image groups (individual images and the group as a whole), image sequences, and video frames</td>
      <td>N/A</td>
      <td>Supports 1 to 2000 embeddings on images, image groups (individual images and the group as a whole), image sequences, and video frames.</td>
    </tr>
  </tbody>
</table>

### Label Validation

Label validation refers to the **Explore** tab inside of your Projects.

<div>
  | **Limit**                    | **Enterprise** | **Team** |
  | ---------------------------- | -------------- | -------- |
  | Maximum number of data units | 500,000        | 500,000  |
</div>

<Tip> Label validation supports up to 750K data units per Project, but we recommend 500K data units per Project.</Tip>

<Info>
  Label validation supports analysis (Advanced Metrics and Embeddings) on images and videos up to 4K resolution. Performance is affected for images and videos over 4K.
  For optimal performance, we strongly recommend downscaling images and videos over 4K to 4K resolution.
</Info>

***

### Workspace

<div>
  | **Limit**               | **Enterprise** | **Team**  |
  | ----------------------- | -------------- | --------- |
  | Maximum number of users | Unlimited      | Unlimited |
</div>

<Tip>Even if you stay within these limits, we recommend creating a new Project every 6 months and archiving the existing Project</Tip>

***

### Access Control

Projects in Encord currently support the following roles:

* **Annotator**: Responsible for completing annotation tasks.
* **Reviewer**: Responsible for completing review tasks.
* **Annotator + Reviewer**: Able to complete both annotator and reviewer tasks.
* **Team manager**: Able to complete both annotator and reviewer tasks and access team management features.
* **Admin**: Full access to all Project features. In order to successfully attach Ontologies and Datasets to a given Project, a user must have Admin permissions against each target resource.

<Tip>
  Learn more about user based access control from here:

  * [Projects](/platform-documentation/Annotate/roles-and-permissions#projects)
  * [Datasets](/platform-documentation/Annotate/roles-and-permissions#datasets)
  * [Ontologies](/platform-documentation/Annotate/roles-and-permissions#ontologies)
</Tip>

<Tip>For collaborative teams using our SDK, we recommend creating a [Service Account](/platform-documentation/General/general-access-keys) and creating and sharing access keys for use with the Service Account. For example, to have several people create Ontologies, Datasets, and Projects programmatically, create an email for the Service Account for use with Encord (for example, `encord-admins@mycompany.com` ) and generate an SSH for that email account.</Tip>

***

### Screen Size

Encord is not supported on small screens such as tablets. The minimum application window resolution must be `800x600`px.

***

### Resolution of Visual Media

The resolution of any videos and images should be limited to 4k pixels (`4096x2160`px) to avoid issues. If you have other requirements, contact us first and we can help evaluate suitability for specific use-cases.

<Note>
  Due to limitations of Chrome browser, unzipped files over 2 GB may cause unstable browser behavior, including crashing. See recommended browsers section below
</Note>

***

### Compression Ratio

Encord supports a Compression Ratio of 10:1.

* \~1 GB (gzipped): The size of the file after compression using a tool like gzip can be  1 GB.
* \~10 GB (unzipped): This represents the original size of the file before compression. It can be 10GB.

***

### Medical Imaging

The following table outlines the recommended browsers for viewing DICOM and NIfTI files in the platform, along with important notes on performance and file size limitations. Review these details to ensure optimal functionality and avoid potential issues when working with large or unzipped files.

<Warning>
  Files compressed in `.gzipped` formats can have very high compression ratios. Encord has a limit of 2GB on unzipped files.
</Warning>

| Modality | Browser | Notes                                                                                                                                                                   |
| -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DICOM    | Firefox | No tab memory limit allows large files to load. However, large files can slow down your computer significantly.                                                         |
| NIfTI    | Firefox | No tab memory limit allows large files to load. However, large files can slow down your computer significantly.                                                         |
| DICOM    | Chrome  | 2 GB limit. Due to limitations of the Chrome browser, unzipped files over 2 GB may cause unstable browser behavior, including crashing. See recommended browsers below. |
| NIfTI    | Chrome  | 2 GB limit. Due to limitations of the Chrome browser, unzipped files over 2 GB may cause unstable browser behavior, including crashing. See recommended browsers below. |

***

## Keyboard Shortcuts

Be sure to check out all the [keyboard shortcuts](/platform-documentation/Annotate/annotate-label-editor#keyboard-shortcuts) available when using the Label Editor, to help speed up your annotations.

***

## Recommended Browser

We recommend the Google Chrome or Brave web-browsers when using Encord. All exceptions are listed in the following table.

| Modality      | Recommended Browser | Notes                                                                                                           |
| ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
| Videos        | Chrome              | Includes image sequences.                                                                                       |
| Images        | Chrome              | Includes image groups. Excludes TIFF files.                                                                     |
| DICOM         | Firefox             | No tab memory limit allows large files to load. However, large files can slow down your computer significantly. |
| NIfTI         | Firefox             | No tab memory limit allows large files to load. However, large files can slow down your computer significantly. |
| Images (TIFF) | Chrome              |                                                                                                                 |

<Tip>
  We recommend [turning off hardware acceleration](https://www.howtogeek.com/412738/how-to-turn-hardware-acceleration-on-and-off-in-chrome/#:~:text=In%20the%20Settings%20menu%2C%20expand,Relaunch%E2%80%9D%20to%20apply%20the%20changes.) in Chrome. Hardware acceleration adds another layer of uncertainty to video rendering in the browser.
</Tip>

<Tip>If you have any questions on the above or are experiencing performance issues, contact us at [support@encord.com](mailto:support@encord.com)</Tip>

## Change Identifier from Email to Display Name

Your email address might not be the best way for team managers, Project Admins, or Platform Admins to identify you in Encord. You can use a *Display name* instead of your email address.

1. Go to **User Profile > Settings**.
   The *Settings* page appears.

   ![Settings page](https://storage.googleapis.com/docs-media.encord.com/static/img/admins/settings/overview/encord-settings-display-name-00.png)

2. Click the **Edit** button in the *Name* row.
   The *Name* field becomes editable.

   ![Change display name](https://storage.googleapis.com/docs-media.encord.com/static/img/admins/settings/overview/encord-settings-display-name.png)

3. Provide the display name you want to use.

4. Press <kbd>ENTER</kbd>.


# SDK Access Keys
Source: https://docs.encord.com/platform-documentation/General/general-access-keys



Access keys provide a secure way to [authenticate](/sdk-documentation/general-sdk/authentication-sdk) with the Encord SDK.

## Workspace Access Keys (Recommended)

<Info>
  Service Account Access keys are tied to the Workspace they are created in and grant access to all resources that the Service Account has access to within the Workspace.
</Info>

<Note>Admins can create 1 Service Account per Workspace. Contact us at [support@encord.com](mailto:support@encord.com) if you need more than 1 Service Account.</Note>

Only Encord Admins (not Project Admins) can create Service Accounts in Encord.

**To create a Service Account:**

1. Go to **Workspace Settings > Service Accounts**.
   The *Service Accounts* page appears.

   ![Create Service Account](https://storage.googleapis.com/docs-media.encord.com/static/img/service-accounts-1.png)

2. Click **Create service account**.

   ![Create Service Account 2](https://storage.googleapis.com/docs-media.encord.com/static/img/service-accounts-2.png)

3. Provide a meaningful name for the service account. The name provided is appended into the email address used by the service account.

4. Provide a meaningful description for the service account.

5. Click **Create service account**.
   A new service account appears in the Service Account list.

6. Click into the service account.

   ![Create Service Account 3](https://storage.googleapis.com/docs-media.encord.com/static/img/service-accounts-3.png)

7. Click **New API key**.

   ![Create Service Account 4](https://storage.googleapis.com/docs-media.encord.com/static/img/service-accounts-4.png)

8. Type a meaningful title for the key.

9. Click **Generate key pair**

10. Click **Add API key**.
    A file downloads to your computer containing the key.

![Create Service Account 5](https://storage.googleapis.com/docs-media.encord.com/static/img/service-accounts-5.png)

11. Return to the **Service Accounts** page.

12. Apply a role to the Service Account:

* **Admin:** Executive privileges over Workspaces such as adding and removing users, and the ability to view all Projects.
* **Member:** No administrative privileges over Workspaces. Can only view Projects they create, or have been invited to.

***

## User-Level Access Keys

<Info>
  User-level Access Keys are tied to the user and grant access to the same resources that user can access in the Workspace. When the user is removed from the Workspace, the Access Key stops working.
</Info>

1. Click the user icon in the bottom-left corner of the UI.

2. Select **User settings**.

<div>
  <img />
</div>

3. Click the **API keys** tab.

4. Click the **New Key** button to add or generate a new key.

5. Give the key a meaningful name.

6. Click **Generate key pair** to generate a new Access Key pair.
   The public key field is automatically populated, and a `.txt` containing your corresponding private key is downloaded.

<div>
  <img />
</div>

7. Click **Add API key** to add your key.
   The key is now listed in the *API keys* section along with an ID that serves as a unique identifier.

<Info>
  Key names do not have to be unique, but the keys themselves do. Attempting to upload a duplicate key results in an error.
</Info>

***

## Using Terminal / Powershell

<AccordionGroup>
  <Accordion title="Create Access Key Using Terminal / Powershell ">
    <Tip>
      We strongly recommend using the Encord UI to generate Access Keys.
    </Tip>

    Follow these steps to generate a public-private key pair using an encryption library. Encryption libraries are part of most major operating systems, therefore you can generate this key pair using the appropriate terminal for your OS:

    * **Linux/macOS**: the default terminal
    * **Windows 10 & Server 2019/2022**: Powershell

    To generate a public-private key pair:

    1. Open Terminal or Powershell.

    2. Run the following command:

       ```
       $ ssh-keygen -t ed25519
       ```

    3. Press enter to accept the default file location or modify as required:

       ```bash Mac theme={"dark"}
       > Enter a file in which to save the key (/Users/YOU/.ssh/id_ALGORITHM): [Modify / Press ENTER]
       ```

       ```bash Windows theme={"dark"}
       > Enter a file in which to save the key (C:\Users\YOU/.ssh/id_ALGORITHM): [Modify / Press ENTER]
       ```

       ```bash Linux theme={"dark"}
       > Enter a file in which to save the key (/home/YOU/.ssh/id_ALGORITHM): [Modify / Press ENTER]
       ```

    4. \[**IMPORTANT**] Leave the passphrase blank:

       ```
       > Enter passphrase (empty for no passphrase): [Press ENTER]
       > Enter same passphrase again: [Press ENTER]
       ```

    <Warning>
      Ensure that the private key you have generated is not protected by a passphrase. Password-protected private keys cannot be [authenticated in Encord](#authenticate-with-your-private-key). All private keys [generated on the Encord platform](#generating-keys-in-encord-recommended) are not password-protected by default.
    </Warning>

    You should now have two files:

    * `/path/to/your/key/id_ALGORITHM` contains your private key (which you should keep secure);
    * `/path/to/your/key/id_ALGORITHM.pub` contains your public key (usually in a file ending in *.pub*).

    The next step is to add your public key to Encord. To add your public key to Encord:

    1. Copy the contents of the public key file. For that, execute:

       ```
       $ cat /path/to/your/key/id_ALGORITHM.pub
         # Then select and copy the contents of the id_ALGORITHM.pub file
         # displayed in the terminal to your clipboard
       ```

    2. Navigate to the 'API keys' section of the user settings to create, register and manage your public keys.

    <div>
      <img />
    </div>

    3. Enter a title for your public key in the first field, and paste your public key in the second field. The **Create** button becomes available once both fields have been populated.

    4. Click **Create** to add your public key to Encord. It is listed showing the key's name, and a signature that serves as a unique identifier.
  </Accordion>
</AccordionGroup>


# Supported Data
Source: https://docs.encord.com/platform-documentation/General/general-supported-data



<Info>To ensure seamless data loading in Encord, allowlist [https://app.encord.com/](https://app.encord.com/) or [https://app.us.encord.com/](https://app.us.encord.com/) in any 3rd party VPNs, firewalls, or URL isolators. This helps prevent potential issues with opening your data in Encord.</Info>

## Supported File Formats

<Tip>
  The Encord platform supports more file formats than those listed below. If you do not see a format you want supported, contact us at [support@encord.com](mailto:support@encord.com).
</Tip>

<table>
  <thead>
    <tr>
      <th>Data Unit Type</th>
      <th>Supported file formats</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Point Cloud Data</td>

      <td>
        * .pcd - Point Cloud Data
        * .ply - Polygon File Format
        * .las - LAS point cloud (up to LAS v1.3)
        * .laz - Compressed LAS (up to LAS v1.3)
        * .mcap - MCAP container
        * .bag - ROS bag files
        * .db3 - ROS2 SQLite bag files
      </td>
    </tr>

    <tr>
      <td>Time Series</td>

      <td>
        * .csv
      </td>
    </tr>

    <tr>
      <td>Single Image</td>

      <td>
        * .jpeg
        * .png
        * .webp
        * .avif
        * .bmp
        * .tiff
        * .tif
      </td>
    </tr>

    <tr>
      <td>Image group</td>

      <td>
        * .jpeg
        * .png
        * .webp
        * .avif
        * .bmp
        * .tiff
        * .tif
      </td>
    </tr>

    <tr>
      <td>Images sequence</td>

      <td>
        * .jpeg
        * .png
        * .webp
        * .avif
        * .bmp
      </td>
    </tr>

    <tr>
      <td>Video</td>

      <td>
        * .mp4
        * .mov\*
        * .webm
        * .mkv

        <Warning>
          \* MOV files are only supported in Safari due to Chromium browser limitations. We recommend using Chrome for all other workflows. [More info here.](https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Formats/Containers)
        </Warning>
      </td>
    </tr>

    <tr>
      <td>Audio</td>

      <td>
        * .mpeg
        * .wav
        * .x-wav
        * .flac
      </td>
    </tr>

    <tr>
      <td>Documents</td>

      <td>
        * .pdf
      </td>
    </tr>

    <tr>
      <td>Text</td>

      <td>
        * .html
        * .json
        * .xml
        * .txt
      </td>
    </tr>
  </tbody>
</table>

***

## Point Cloud Data

PCD Projects use "Scenes". Scenes are the data units that your Taskers, and possibly your Agents, work with to create and review your labels.

A Scene can be one of the following:

* A single PCD file (.pcd, .ply, .las, .laz, and so on)

* A group of videos and PCD files bound together as a coherent group.

Encord supports the following formats for Point Cloud Data:

* .pcd - Point Cloud Data
* .ply - Polygon File Format
* .las - LAS point cloud (up to LAS v1.3)
* .laz - Compressed LAS (up to LAS v1.3)
* .e57 - E57 point cloud
* .mcap - MCAP container
* .bag - ROS bag files
* .db3 - ROS2 SQLite bag files

<Note>
  Encord supports the following for multimodal Scenes:

  * Videos up to 1GB in size
  * Single point cloud files up to 20 million points/200-300 MB
  * Up to 9 videos in a Scene
  * Up to 1000 frames in each Scene
  * Up to 50 cloud data points per frame. We downsample to 10 million points per frame when points per frame exceeds 10 million.
</Note>

## Single images

Single images are individual images that are uploaded to Encord as separate files. Each single image constitutes its own data unit, hence images are listed individually.

We support the following file types for single images:

<div>
  `.jpeg`,  `.png`,   `.webp`,  `.avif`,  `.bmp`,  `.tiff`\*,   `.tif`\*
</div>

<Tip>
  To learn how to upload images from your cloud storage, follow the links below:

  * [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format)
  * [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format)
</Tip>

***

## Image groups

Image groups are collections of images that are grouped together into a single data unit. They can contain images of varying orientations and no data is lost in the process of creating an image group.

<Tip>
  For faster uploads, use image groups instead of image sequences. Image groups bundle multiple images into a single data unit, while image sequences convert images into a video, which requires more processing power and time.
</Tip>

We support the following file types for image groups:

<div>
  `.jpeg`,  `.png`,   `.webp`,  `.avif`,  `.bmp`,  `.tiff`\*,   `.tif`\*
</div>

<Warning>\* Due to Chromium-based browser limitations, TIFF files can only be viewed in the Label Editor using the Safari browser.</Warning>

<Tip>
  To learn how to upload image groups from your cloud storage, follow the links below:

  * [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format)
  * [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format)
</Tip>

***

## Image sequences

Image sequences are collections of images that are grouped together into a single data unit, and annotated in the same way as videos. As a result, image sequences are able to make use of powerful machine learning features such as automated labeling.

<Info>
  Only images with the same dimensions can be combined into an image sequence. If your upload includes images with varying dimensions, a separate image sequence is created for each unique dimension.
</Info>

<Tip>
  For faster uploads, use image groups instead of image sequences. Image groups bundle multiple images into a single data unit, while image sequences convert images into a video, which requires more processing power and time.
</Tip>

We support the following file types for image sequences:

<div>
  `.jpeg`,  `.png`,   `.webp`,  `.avif`,  `.bmp`,  `.tiff`\*,   `.tif`\*
</div>

<Tip>
  To learn how to upload image sequences from your cloud storage, follow the links below:

  * [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format)
  * [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format)
</Tip>

#### Creating image sequences

Image sequences can be created [when importing files into Encord](/platform-documentation/Curate/index-files#create-image-groups-and-image-sequences), or by [batching images in **Data** > **Files & Folders**](/platform-documentation/Curate/files/index-batch-images) into image sequences.

<Info>
  Only images with the same dimensions can be combined into an image sequence. If your upload includes images with varying dimensions, a separate image sequence is created for each unique dimension.
</Info>

***

## Videos

Video files can be uploaded or registered on the Encord platform and annotated frame by frame, allowing you to track elements throughout the video. While each frame is treated as an individual image during annotation, the video remains a single data package.

The following video formats, contains, and codecs are supported.

| Video Formats and Containers | Supported Codecs |
| ---------------------------- | ---------------- |
| matroska, webm               | vp8              |
| matroska, webm               | vp9              |
| matroska, webm               | libdav1d         |
| mov, mp4, m4a, 3gp, 3g2, mj2 | libdav1d         |
| mov, mp4, m4a, 3gp, 3g2, mj2 | h264             |
| mov, mp4, m4a, 3gp, 3g2, mj2 | h265 (hevc)      |

<Note>VP9 in an MP4 container is supported but not verified in all environments.</Note>

For optimized performance we recommend using the following video formats:

* **`.mp4` with `H.264`** –  We recommend using H.264 as the default codec, unless you have specific requirements that necessitate H.265. H.265 may present compatibility issues in some cases.
* **`.mp4` with `VP9`**.

File uploads must be less than 1 GB or 200,000 frames (2hr at 30FPS). See our [guidelines for optimal performance](/platform-documentation/General/best-practices#guidelines-for-optimal-performance) for more details.

<Tip>
  Use the following pages to learn how to upload videos from your cloud storage.

  * [JSON](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format)
  * [CSV](/platform-documentation/Curate/add-files/index-register-cloud-data#csv-format)
</Tip>

### Resizing Videos

Videos can be re-sized using `ffmpeg` to fit the required specifications in the following ways:

* Lowering their resolution.
* Lowering their frame rate.
* Specify a key frame interval.

Follow the steps below to reduce the video file size by adjusting the resolution, as well as the number of frames per second (fps).

1. Download and install `ffmpeg`.
2. Open Command Line (on Windows) or Terminal (on Mac & Linux).
3. Run the command shown below, substituting the values for your desired resolution as well as fps, followed by the path to the video you'd like to downsize.

```shell theme={"dark"}
ffmpeg -i normal-video.mp4 -c:v libx265 -an -movflags faststart -tune zerolatency -f mp4 -vf "scale=-1:1080,fps=30" </Users/Desktop/normal-video-downsampled.mp4>
```

The example above resizes `normal-video-downsampled.mp4` to `30 fps` and a resolution of `-1:1080px`. This means that the video height is set to `1080px`, while the `-1` adjusts the width so that the aspect ratio remains the same as in the original.

The following example imports the video by generic key frame intervals using the global variable `-g` (every 30 frames).

```shell theme={"dark"}
ffmpeg -i normal-video.mp4 -c:v libx265 -an -movflags faststart -tune zerolatency -f mp4 -g 30 </Users/Desktop/normal-video-downsampled.mp4>
```

The following example imports the video by key frame intervals by specific codec `-x264opts keyint=` (every 30 frames for codec H264).

```shell theme={"dark"}
ffmpeg -i normal-video.mp4 -an -movflags faststart -tune zerolatency -f  -c:v libx264 -x264opts keyint=30" </Users/Desktop/normal-video-downsampled.mp4>
```

<Tip>[Click here](http://trac.ffmpeg.org/wiki/Scaling) to learn more about scaling with ffmpeg.</Tip>

<Warning>Decreasing a video's resolution and/or frame rate reduces its quality, making this option suitable only for customers who do not require high-quality videos.</Warning>

### Pixel aspect ratio

To ensure accurate labels, only videos with a [pixel aspect ratio](https://en.wikipedia.org/wiki/Pixel_aspect_ratio) of 1:1 should be used in Encord.

To check the pixel aspect ratio of your file, run the following `ffprobe` command, where `input-file.mp4` is the full file path to the file you want to output the pixel aspect ratio for. `ffprobe` refers to pixel aspect ratio as 'sample aspect ratio (SAR)'.

```bash theme={"dark"}
ffprobe -v error -select_streams v:0 -show_entries stream=sample_aspect_ratio -of default=noprint_wrappers=1:nokey=1 input-file.mp4
```

<Warning>The `ffprobe` command outputs 'N/A' if the file's SAR is not defined in the video's metadata.</Warning>

***

### Converting Videos to Images

In machine learning, most infrastructures and codebases are tailored for image data rather than video. Therefore, when working with videos, a common prerequisite is to convert videos into a series of images. This process is essential for training ML models that do not directly support video inputs. We outline two approaches for extracting images from videos, each catering to different needs.

**Approach 1: Extracting Every Frame as an Image**

<Note>This approach requires `ffmpeg`. Download and install `ffmpeg` if you have not already. </Note>

This method involves decompressing each frame of a video into separate image files. It's straightforward and useful when you need to analyze or process every frame individually. Navigate to the directory your video is in and run the following command in your Terminal, replacing `your_video.mp4` with the name of your video file, and  `/path/to/output/dir/frame` with the path to your output directory.

```Terminal theme={"dark"}

ffmpeg -i your_video.mp4 -start_number 0 /path/to/output/dir/frame_%d.png -hide_banner

```

**Approach 2: In-Memory Frame Iteration with Python**

For scenarios where saving individual image files is unnecessary, you can iterate over video frames directly in memory using Python. This method is efficient for immediate processing or conversion to formats like TFRecords.

<Note>This approach requires that the `pyav` Python library is installed. </Note>

```python theme={"dark"}

import av

# Open the video file
with av.open('your_video.mp4') as container:
    # Loop through streams in the container
    for frame in container.decode(video=0):
        # Process the frame. For example, convert the frame to a PIL Image and show it
        img = frame.to_image()
        img.show()

```

***

## DICOM & NIfTI

Encord provides native support for Digital Imaging and Communications in Medicine (DICOM) & Neuroimaging Informatics Technology Initiative (NIfTI) browser rendering and data annotations.

Our [Ontologies](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) allow you to create any type of labeling protocol - for example RECIST, which requires measuring the longest diameter of a lesion.

With the DICOM editor, you can:

* Annotate modalities such as CT, X-ray, MRI, , Mammograms, and Retinal Fundoscopy images.
* Label using any annotation type in 2D (with 3D in the works), and seamlessly toggle between axial, coronal, and sagittal views.
* Render 20,000 pixel intensities and set custom window widths & levels.
* Natively display DICOM metadata.
* Track and interpolate objects between slices.
* Reduce manual annotations with automation features.

<Note>Due to DICOM being a large and open standard Encord accepts most data types. Examples include: CT, MR, US, MG, TOMO, but many more are accepted.</Note>

<Tip> Learn how to upload DICOM files from your cloud storage [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format)</Tip>

### Multi-frame DICOM Support

We support multi-frame DICOMs, making it even easier and faster to load data onto our platform! Multi-frame DICOM support can save time and streamline workflows due to a reduced amount of header data repetition.

Simply upload your multi-frame DICOM files like you would any other files - either via the user interface, or using our python SDK.

### Caching DICOM data

Caching allows frequently accessed DICOM files to be stored securely in your local browser memory, allowing them to be retrieved quickly and efficiently. As a result you can expect faster load times when accessing medical imaging data.

This is particularly beneficial for busy healthcare professionals who require quick access to patient records and diagnostic imaging.

***

## Re-encode Videos

<Info>Re-encoding within the Encord platform is only available to Enterprise customers. Contact [sales@encord.com](mailto:sales@encord.com) for more information.</Info>

Encord automatically checks all uploaded videos for re-encoding, a process that ensures they meet our platform's requirements. This prevents [frame synchronization issues](/platform-documentation/General/general-supported-data#frame-synchronization-issues) and guarantees accurate labels.

If a video requires re-encoding, a red badge on the file icon indicates the number of issues. You can view each issue by selecting the file and checking the details pane or by hovering over the badge.

<div>
  <img />
</div>

## How to Re-Encode

<Tip>
  You can Re-encode your videos in the **Files & Folders** or **Datasets** interfaces, but we strongly recommend doing so at the **Files & Folders** level. Videos re-encoded at the Folder level can be used in any Project, while those re-encoded at the Dataset or Project level are restricted to their associated resources.
</Tip>

### Re-encode from Folders

<Info>Re-encoding is only available to Enterprise customers. Contact [sales@encord.com](mailto:sales@encord.com) for more information.</Info>

1. Go to **Data > Sources**.

2. Go into the Folder where the video you want to re-encode resides.

3. Perform one of the following:

* Right-click the video and select **Re-encode** and select the [type of re-encoding](/platform-documentation/Curate/files/files-re-encoding#types-of-re-encoding) to perform.
* Select one or more videos and click **Actions > Re-encode** and select the type of re-encoding to perform.

<div>
  <img />
</div>

4. Check the progress of the re-encoding job by clicking the bell icon in the top-right of the app.

<Info>
  When the process is complete a new video file with the word "normalized" appended to the name appears in the folder. For example, if you re-encoded `snowboard.mp4`, the new video is `snowboard_normalized.mp4`.
</Info>

### Re-encode from Datasets

<Info>Re-encoding is only available to Enterprise customers. Contact [sales@encord.com](mailto:sales@encord.com) for more information.</Info>

1. Go to **Data** > **Datasets**.
   A list of all Datasets available appears on the *Datasets* page.

2. Go into the Dataset where the video you want to re-encode resides.

3. Select one or more videos.

4. Click **Re-encode** and select the [type of re-encoding](/platform-documentation/Curate/files/files-re-encoding#types-of-re-encoding) to perform.

5. Check the progress of the re-encoding job by clicking the bell icon in the top-right of the app. The number displayed in red signifies how many new notifications you have.

When the process is complete a new video file with the word "normalized" appended to the name appears in the folder. For example, if you re-encoded `snowboard.mp4`, the new video is `snowboard_normalized.mp4`.

## Types of Re-encoding

### Automatically fix detected issue

<div>
  <img />
</div>

**Re-encode (Auto)**: Encord performs a spot fix for any detected encoding issues. This is quicker than a full re-encoding, but for some issues, a full re-encoding is required.

### Force full re-encoding

<div>
  <img />
</div>

**Re-encode (Full)**: Encord performs a full re-encoding of the video to a specific frame rate and video codec, regardless of the issues detected. This method ensures all issues are resolved, but it can take significantly more time to perform.

### Re-encode Locally

Some cases, such as corrupted metadata, might require you to re-encode your data locally before uploading them to the Encord platform.

Use the following `ffmpeg` command, replacing `video.mp4` with the name of the file you want to re-encode, and `re-encoded-video.mp4` with the name you want the re-encoded file to have:

```bash theme={"dark"}
ffmpeg -err_detect aggressive -fflags discardcorrupt -i video.mp4 -r 30 -c:v libx264 -movflags faststart -an -tune zerolatency re-encoded-video.mp4
```

<Warning>
  Since browsers require a constant frame rate, we apply the -r 30 flag (30 fps). Verify your video’s frame rate and adjust the value accordingly.
  We recommend using the average frame rate of your video to set the constant rate (rounded to the nearest whole number).

  You can figure out the average frame rate of your video with this command:

  ```bash theme={"dark"}
  ffprobe -v 0 -select_streams v:0 -show_entries stream=r_frame_rate -of default=noprint_wrappers=1:nokey=1 video.mp4 | bc -l
  ```

  You may need to install `ffprobe` & `bc`
</Warning>

<Note>
  Here is a summary of the various flags:

  * `-err_detect aggressive`: Improves error detection during decoding.
  * `-fflags discardcorrupt`: Discards corrupted packets to maintain integrity.
  * `-r 30`: This sets the frame rate to a constant 30 frames per second (FPS). Feel free to adjust `30` to your desired frame rate.
  * `-c:v libx264`: Specifies the `H.264` codec for video re-encoding.
  * `-movflags faststart`: Optimizes for web playback by moving video metadata to the beginning of the file.
  * -an: This ensures the audio is removed from the re-encoded video.
  * `-tune zerolatency`: Configures for low-latency encoding scenarios.
</Note>

### Frame Synchronization Issues

Our servers use `FFmpeg` to extract video frames individually, ensuring precise label alignment. This process assigns each label to a specific frame index for accurate mapping within the video. However, a video's frame rate can be inconsistent when embedded in a browser, which may affect the synchronization of displayed frames.

If we detect any of the following frame synchronization issues after uploading a video your video must be [re-encoded](/platform-documentation/General/general-supported-data#re-encode-videos).

<AccordionGroup>
  <Accordion title="Audio frames">
    A video has "audio frames" whenever the video has any audio with it. We have observed unexpected behavior where the browser video player would sometimes increase the display length of specific frames when audio frames were present. As we can only seek frames by timestamps in the browser, whenever we detect audio frames we recommend to remove those.

    **Detecting the problem:**

    * Check the warnings on the Encord platform.
    * Listen for sound in the video. Unfortunately this is not a guarantee as sometimes there can be audio frames even when there is no audible sound present.
    * By running:

    ```bash theme={"dark"}
    ffprobe -i $YOUR_FILE -show_streams -select_streams a -loglevel error
    ```

    If there is no output, there are no audio frames. If you see some output, there are some audio frames.

    **Fixing the problem:**

    Re-encode the video in the Encord platform. This will copy all the video frames but will drop all the audio frames.
  </Accordion>

  <Accordion title="Ghost frames">
    The issue known as "ghost frames" arises when video frames have negative timestamps. This can happen when videos are cut at the beginning, but a keyframe with a negative timestamp is retained.

    Various video players may display a varying number of frames with negative timestamps, ranging from 0 to all. Unfortunately, we have no control over the browser's video player, so we cannot predict how many negative keyframes it will display.

    To ensure accurate labeling, we must avoid labeling any frames with negative timestamps. Therefore, we kindly request that you re-encode the video to remove any negative timestamps. This process will resolve the "ghost frames" issue and ensure smooth annotation.

    **Detecting the problem:**

    * Check the warnings on the Encord platform.
    * By using different media players and observing whether some of them start at different frames in the video.
    * By running:

    ```bash theme={"dark"}
    ffprobe -show_packets -select_streams v -read_intervals %+3 -of json $YOUR_FILE
    ```

    This will show the video packets of the first 3 seconds in a JSON format.
    You will see an output such as

    ```bash theme={"dark"}
        [...]
        "packets": [
            {
                "codec_type": "video",
                "stream_index": 0,
                "pts": -16384,
                "pts_time": "-1.066667",
                "dts": -16896,
                "dts_time": "-1.100000",
                "duration": 512,
                "duration_time": "0.033333",
                "size": "71396",
                "pos": "37476",
                "flags": "KD"
            },
            [...]
    ```

    If in any of the packets you have a negative value for `pts`, you know that there might be some ghost frames.

    **Fixing the problem:**

    Re-encode the video in the Encord platform. These are the transformations we apply when we detect ghost frames:

    * The audio frames are dropped.
    * The video frames are re-encoded (i.e. the images in the videos are decompressed and compressed again).
    * All unsupported file formats are converted to `.mp4` files.
    * Corrupted frames are dropped.
  </Accordion>

  <Accordion title="Variable frame rates">
    Some videos have variable frame rates. This could come for example from a dashcam which tries to write frames as fast as it can.

    **Detecting the problem:**

    * Check the warnings on the Encord platform
    * Run the same ffprobe command as for ghost frames (above) and check if the distance between the `pts` is  variable

    **Fixing the problem:**

    Re-encode the video in the Encord platform. These are the transformations we apply when we detect a variable frame rate:

    * A constant frame rate is applied to the video. This requires some dropping and duplicating of frames and is handled by the `-vsync cfr` FFmpeg flag.

    * All the transformations that are applied to videos with ghost frames.
  </Accordion>
</AccordionGroup>

You may also see a frame synchronization warning in the Label Editor when trying to open the video task:

<div>
  <img />
</div>

For a more detailed check, you can use `ffprobe` (part of the FFmpeg suite) to inspect your video's properties.

#### Existing labels before re-encoding

When you upload pre-existing labels for a video that requires re-encoding, there is a risk that your labels might become misplaced. This can occur for two reasons:

* The original labels were created incorrectly due to frame synchronization issues on other platforms.
* The video's variable frame rate changed during re-encoding.

If you re-encode your video, we strongly encourage verify the accuracy of your pre-existing labels. Should you find that your labels are misaligned, contact the support assistance.

***

## Supported Browsers

We recommend the Google Chrome or Brave web-browsers when using Encord.

<Tip>
  * We recommend [disabling hardware acceleration](https://www.howtogeek.com/412738/how-to-turn-hardware-acceleration-on-and-off-in-chrome/#:~:text=In%20the%20Settings%20menu%2C%20expand,Relaunch%E2%80%9D%20to%20apply%20the%20changes) in Chrome when working with **videos** or **image sequences**, as it can cause rendering issues and unexpected behavior in the browser.
  * We recommend **enabling** hardware acceleration when working with [**PCD Scenes**](/platform-documentation/Curate/add-files/add-pcd-data) to ensure smoother performance and faster rendering.
</Tip>

### HEVC (High Efficiency Video Coding)/H265 Support

HEVC (High Efficiency Video Coding), also known as H265, requires at least the following hardware specs for a good experience:

* 4GB of RAM
* Mac: 2016 (or later) or any M series
* Windows: AMD Ryzen or Intel 7th gen

<Note>If your computer has the above specs and continues to have issues with H265 videos, we recommend re-encoding the videos as h.264 encoding.</Note>


# Workspace Analytics
Source: https://docs.encord.com/platform-documentation/General/general-workspace-analytics



<Warning>
  Only Workspace Admins have access to the Workspace Analytics page.
</Warning>

Your Workspace's analytics can be accessed by navigating to **Analytics**.

<div>
  <img />
</div>

## Overview

<div>
  <img />
</div>

The **Overview** section shows the following:

| Metric                   | Description                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Total tasks submitted    | Total number of (annotation and review) tasks submitted across all Projects in your Workspace during the specified time period. |
| Total time spent         | Total time spent in the Label Editor by all Workspace users during the specified time period.                                   |
| Total annotation time    | Total active time spent annotating in the Label Editor by all Workspace users during the specified time period.                 |
| Total files uploaded     | Number of files uploaded to Encord during the specified time period.                                                            |
| Instance labels created  | Total number of instance labels created in your Workspace during the specified time period.                                     |
| Avg. time spent per task | Average time spent per task on annotation and review in the Label Editor by all users during the specified time period.         |
| Total review time        | Total active time spent reviewing in the Label Editor by all Workspace users during the specified time period.                  |
| Total folders created    | Number of folders created in Index during the specified time period.                                                            |

***

## Activity

<div>
  <img />
</div>

The **Activity** section shows the following:

* **Projects**: Displays the total number of Projects in your Workspace for the selected time period. A chart breaks down the status of all Projects by count and percentage.

* **Most Active Users**: Highlights the top 5 users based on activity within the Label Editor during the selected time period, including the total active time for each user.

* **Most Active Projects**: Highlights the top 5 Projects with the most activity in your Workspace during the selected time period.

* **Time Spent**: Visualizes daily activity across the selected time period. You can toggle between views: *Total*, *By Stage*, and *By Project*.

***

## Collaborators

<div>
  <img />
</div>

The *Collaborator overview* shows analytics for each Workspace member across all Projects in the selected time period.

| Column Name           | Description                                                                                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User                  | The user's email address.                                                                                                                                                                                                       |
| User role             | The user's role within the Workspace. Can be *Admin*, *Member*, *Workforce Manager*, or *Collaborator*.                                                                                                                         |
| Groups                | A list of user groups the user is a member of.                                                                                                                                                                                  |
| Projects active in    | The number of Projects the user was active in during the selected time period. Does not include Projects where the user had no activity in the Label Editor.                                                                    |
| Submitted tasks       | Number of tasks submitted by the user during the selected time period.                                                                                                                                                          |
| Skipped tasks         | Number of tasks the user skipped during the selected time period.                                                                                                                                                               |
| Approved tasks        | Number of reviews approved for tasks submitted by the user in an Annotate Stage during the selected time period.                                                                                                                |
| Rejected tasks        | Number of reviews rejected for tasks submitted by the user in an Annotate Stage during the selected time period.                                                                                                                |
| Task rejection rate   | Percentage of submitted tasks that received a rejection in review during the selected time period.                                                                                                                              |
| Created labels        | Number of labels created by the user in an annotation stage during the selected time period.                                                                                                                                    |
| Edited labels         | Number of labels edited by the user in an Annotation stage, or during [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review) in the selected time period. |
| Deleted labels        | Number of labels deleted by the user in the selected time period.                                                                                                                                                               |
| Total time            | Total time the user spent in the Label Editor (annotation or review) during the selected time period.                                                                                                                           |
| Total annotation time | Total active time the user spent annotating in the Label Editor during the selected time period.                                                                                                                                |
| Total review time     | Total active time the user spent reviewing in the Label Editor during the selected time period.                                                                                                                                 |
| Avg time per task     | Average time the user spent on each annotation or review task in the Label Editor during the selected time period.                                                                                                              |
| Last project activity | The most recent date the user was active in any Project.                                                                                                                                                                        |
| Joined date           | The date the user was added to the Workspace.                                                                                                                                                                                   |

***

## Projects

<div>
  <img />
</div>

The *Project overview* shows analytics all Projects in your Workspace in the selected time period.

| Column Name           | Description                                                                                                                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Project name          | The name of the Project.                                                                                                                                                                                                                   |
| Status                | Current status of the Project. Can be *Cancelled*, *Paused*, *Completed*, *Not Started*, or *In Progress*.                                                                                                                                 |
| Progress              | Percentage of task completion in the Project.                                                                                                                                                                                              |
| Total files           | Total number of files associated with the Project, based on the contents of the attached Datasets.                                                                                                                                         |
| Processed files       | Number of files that have been processed in the Project.                                                                                                                                                                                   |
| Submitted tasks       | Total number of tasks submitted across all workflow stages in the Project during the selected time period.                                                                                                                                 |
| Approved tasks        | Number of tasks approved in the review stage(s) of the Project during the selected time period.                                                                                                                                            |
| Rejected tasks        | Number of tasks rejected in the review stage(s) of the Project during the selected time period.                                                                                                                                            |
| Task rejection rate   | Percentage of submitted tasks rejected during review in an Annotate Stage of the Project, for the selected time period.                                                                                                                    |
| Created labels        | Number of labels created in the Project during annotation within the selected time period.                                                                                                                                                 |
| Edited labels         | Number of labels edited in the Project during in any Annotation stage, or during [Edit Review](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#edit-labels-during-review) in the selected time period. |
| Approved labels       | Number of labels approved during review in the Project within the selected time period.                                                                                                                                                    |
| Rejected labels       | Number of labels rejected during review in the Project within the selected time period.                                                                                                                                                    |
| Total time            | Total time spent in the Label Editor on this Project, including both annotation and review, during the selected time period.                                                                                                               |
| Total annotation time | Total active time spent annotating in the Project during the selected time period.                                                                                                                                                         |
| Total review time     | Total active time spent reviewing in the Project during the selected time period.                                                                                                                                                          |
| Avg. time per task    | Average time spent per task (annotation and review) in the Label Editor during the selected time period.                                                                                                                                   |
| Avg. time per label   | Average annotation time per label, calculated as total annotation time divided by the number of labels created in an Annotate Stage, for the selected time period.                                                                         |
| Issue Tags Count      | Total number of issue tags added in the Project during the selected time period.                                                                                                                                                           |
| Avg. daily throughput | Average number of tasks submitted per day within the selected time period.                                                                                                                                                                 |
| Project owner         | The user who created the Project.                                                                                                                                                                                                          |
| Tags                  | A list of Project tags associated with the Project.                                                                                                                                                                                        |
| Groups                | A list of user groups added to the Project.                                                                                                                                                                                                |
| Active users          | Number of users with recorded active time in the Label Editor for this Project during the selected time period.                                                                                                                            |
| Created at            | The date that the Project was created.                                                                                                                                                                                                     |

***

## Workspace Analytics Emails

You can subscribe to receive an overview of your Workspace's analytics by email. Workspace Analytics emails are sent to the same address you use to log in to Encord. Workspace Analytics emails are sent from [insights@encord.com](mailto:insights@encord.com) and are labeled with the subject `insights`.

**To start receiving Workspace analytics emails**:

1. Click the **Subscribe** button in the top-right corner of the Workspace Analytics page.

2. Set the frequency to receive Workspace Analytics emails.

<Note>
  You can choose to receive notifications weekly or monthly.

  * Weekly notifications are sent on the specified day of the week.
  * Monthly notifications are sent on a designated day of the month.

  If you select “End of the month,” emails are sent on the last day of each month, regardless of the date.
</Note>

3. Click **Subscribe**.

<div>
  <img />
</div>

**What does the Workspace Analytics email contain**:

<div>
  <img />
</div>

<Tip>
  Click **View detailed analytics** to see the full Workspace Analytics page in Encord.
</Tip>

* **Metric Overview** shows the following, since the last email update.

| Field                 | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| Files uploaded        | Total number of files uploaded since the last email.                   |
| Tasks submitted       | Total number of tasks submitted since the last email.                  |
| Labels created        | Total number of labels created since the last email.                   |
| Time spent            | Total time spent in the Label Editor since the last email.             |
| Avg. time per task    | Average time spent per task since the last email.                      |
| Active users          | Total number of users actively using the product since the last email. |
| Total files uploaded  | Total files uploaded this year.                                        |
| Total tasks submitted | Total tasks submitted this year.                                       |
| Total labels created  | Total labels created this year.                                        |
| Total time spent      | Total time spent this year.                                            |
| Avg. time per task    | Average time spent per task this year.                                 |

* **Most Active Projects** shows a list of the 5 most active Projects in your Workspace, including the time spent on each Project and the number of labels created.

<div>
  <img />
</div>

***

## Share Workspace Analytics

You can share a link to the Workspace Analytics page with other Workspace admins.

1. Click **Share** in the top-right corner of the Workspace Analytics page.

2. Click **Share** again to copy a link to the Workspace Analytics page to your clipboard.

<div>
  <img />
</div>


# Workspace Basics
Source: https://docs.encord.com/platform-documentation/General/general-workspace-basics



<Note>Only Workspace admins can see and access Workspace Settings and Analytics</Note>

## What is a Workspace?

Your Workspace represents your company's environment within the Encord platform. The Workspace dashboard is where you manage and keep track of all users, Projects and Datasets that belong to your Workspace in Encord.

### Entity Relationships

The following diagram shows how entities in Encord are organized.

```mermaid theme={"dark"}
erDiagram
    Workspace {
    }
    Project {
    }
    Dataset {
    }
    Ontology {
    }
    Workflow {
    }

    Workspace ||--o{ Project : "contains"
    Workspace ||--o{ Dataset : "contains"
    Workspace ||--o{ Ontology : "contains"
    Workspace ||--o{ Workflow : "contains"

    Project ||--o| Dataset : "attaches"
    Project ||--o| Ontology : "attaches"
    Project ||--o| Workflow : "follows"
```

* Users are invited to, and entities are created within a Workspace.
* Projects bring together Ontologies, Datasets, and Workflows.
* A Project can have multiple Datasets attached to it, but only one Ontology.
* One Ontology can be attached to multiple Projects.

***

## Multiple Workspaces

Enterprise customers can have multiple Workspaces, each with its own users, Projects, and Datasets. Users can belong to more than one Workspace and hold different roles in each. A user's role in a specific Workspace determines their access and permissions.

**To switch between Workspaces**:

<div>
  <img />
</div>

1. Select the Workspace switcher dropdown displaying the current Workspace's name.
2. Choose the Workspace you want to switch to from the list.

<Note>Workspaces are displayed in alphabetical order in the switcher dropdown for easier navigation.</Note>

***

## Creating Workspaces

When you join Encord we create your Workspace for you, with one or more individuals from your business as Admins of the Workspace.

<Note>
  Contact support if you want Encord to create a Workspace alias that is displayed to 3rd party workforces with the [Tasker or Workforce Manager](/platform-documentation/General/general-workspace-settings#user-roles) user roles.
</Note>

<Tip>We offer the flexibility to associate any email domains with your company's Workspace. This way, when users sign up using a specific email domain, they are automatically integrated into your Workspace. You have the option to assign different [user roles](/platform-documentation/General/general-workspace-settings#user-roles) based on the email domain - typically, email addresses with your company's domain are designated as *Internal* roles, while other chosen domains can be categorized under *Workforce* or *External* roles.</Tip>

***

## Enforce Multi-Factor Authentication

To ensure the security of all your Workspaces, Encord can enforce multi-factor authentication (MFA). Once enabled, members are prompted to set up MFA and cannot log in until it is configured. To enable this feature, contact [support@encord.com](mailto:support@encord.com).

<Tip>Learn how to [enable MFA here](/platform-documentation/Annotate/annotate-settings-general#multi-factor-authentication).</Tip>


# Workspace Settings
Source: https://docs.encord.com/platform-documentation/General/general-workspace-settings



Your Workspace's settings can be accessed by navigating to **My workspace** / **Workspace Settings**.

<Info>
  Workspace settings—including user management—can only be managed through the UI, NOT using the SDK.
</Info>

**To access Workspace settings:**

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

## Users

The **Users** tab of your Workspace settings provides an overview of all your Workspace's users and their user roles.
![Workspace settings - Users](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-users.png)

### User Roles

Workspaces have several kinds of users. The following table outlines permissions for all user roles.

| Permissions                                            | **Admin** | **Workforce Manager** | **Member** | **Tasker** |
| ------------------------------------------------------ | :-------: | :-------------------: | :--------: | :--------: |
| Add and remove users                                   |     ✅     |     (Only Taskers)    |      ❌     |      ❌     |
| View all Projects, Datasets, and Ontologies            |     ✅     |           ❌           |      ❌     |      ❌     |
| Create Projects, Datasets, and Ontologies              |     ✅     |           ✅           |      ✅     |      ❌     |
| Access Projects, Datasets, and Ontologies (if invited) |     ✅     |           ✅           |      ✅     |      ✅     |
| Create user groups                                     |     ✅     |           ✅           |      ❌     |      ❌     |
| Can see other Workspace members                        |     ✅     |           ✅           |      ✅     |      ❌     |

<Note>In addition to having a user role within the Workspace, all users have distinct roles in [Projects](/platform-documentation/Annotate/roles-and-permissions#projects), [Datasets](/platform-documentation/Annotate/roles-and-permissions#datasets), and [Ontologies](/platform-documentation/Annotate/roles-and-permissions#ontologies). </Note>

### Adding and Removing Users

<Note>Only Workspace Admins and Workforce managers have the ability to add users to, or remove users from, the Workspace.</Note>

Users belonging to your Workspace are managed on the *Users* tab of your Workspace settings dashboard. The *Users* tab displays by default when you navigate to your Workspace. All users belonging to your Workspace are listed on the *Users* tab.

**To invite new users to your Workspace:**

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Click the **+ Invite users** button.

   A dialog appears.

   ![Add user - Invitation](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-users-add-04.png)

5. Type the email addresses of the users you want to invite.
   ![Add user - Email address](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-user-add-005.png)

6. Press <kbd>ENTER</kbd>.

7. Select the role you want the users to have.

8. Click **Invite** to invite the users to your Workspace.

   The user appears in the User list.

   ![Add user - User list](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-user-add-008.png)

<Note>
  Users can accept invitations from the email link or a notification on their Encord home screen. The email link always takes them to the Encord login page, regardless of whether they have an existing account.
</Note>

<Tip>
  Invitations that have not been accepted by the invitee can be resent by clicking the **Resend** button in the **Status** column.
</Tip>

**To remove users from your Workspace or revoke pending invitations:**

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Search for the user you want to remove from your Workspace.

   ![Remove user](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-user-delete-04.png)

5. Click **User details**.

   A dialog appears.

   ![Remove user - delete](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-user-remove-05.png)

6. Click the **Delete** icon.

If the user being removed is the sole Admin for any Projects or Datasets within the Workspace, you are prompted to select a replacement user from within your Workspace.

<Note>Admins cannot be removed from a Workspace. To remove an Admin from your Workspace, contact [support@encord.com](mailto:support@encord.com).</Note>

### Accepting Invites

When a user is invited to join a Workspace, they need to accept the invitation sent to their email in order to join.

1. Open the Email.

<div>
  <img />
</div>

2. Click **Accept invite**.

<div>
  <img />
</div>

3. If you have not registered with Encord before, set up a password and add your name.

<div>
  <img />
</div>

4. Accept the invitation to the Workspace.

<div>
  <img />
</div>

The user has now joined the Workspace. Any Projects the user was added to appear in their list of Projects.

### Status

The user's status shows the status of the invitation to your Workspace. Users can have the following status:

* **Invited**: Shows the date the user was invited to your Workspace. The invitation is pending.
* **Declined**: Shows the date the user declined the invitation to join your Workspace.
* **Joined**: Shows the date the user joined your Workspace.

### Changing User Roles

<Note>
  Only Workspace admins can change user roles in your Workspace.
</Note>

<Warning>
  The roles of Workspace Admins cannot be changed. To change the user role of an Admin, or to remove them from the Workspace, contact [support@encord.com](mailto:support@encord.com).
</Warning>

**To change a user's role within the workspace**:

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Search for the user you want to change the user role for.

5. Click the user role dropdown of the user.

6. Select the role you want the user to have.

<div>
  <img />
</div>

**To change a user's role for a resource**:

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Click **User details** in the **Action** column for the user.

5. Click the user's current role in the Role column, then select the new role you want to assign for the resource.

<Tip>
  Click **Change role** from the **Bulk actions** dropdown to change a user's role in multiple Projects at once.

  <div>
    <img />
  </div>
</Tip>

### Assigning Users

Users can be assigned to various resources even before the users accepts their invitation to join your Workspace.

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click **User details** in the **Action** column for the user you want to assign.

3. Select the resource you want to assign a user to by clicking the relevant tab.

4. Click the **Assign to** button. Different resources have different resource names on the button.

5. Select all the resources you want to assign the user to from the list. Use the search bar to search for a specific resource if necessary.

6. Click **Select a role**.

7. Select a role for the user. The role is assigned for all selected resources.

8. Click **Assign to annotation projects** to assign the user to your selected Projects.

**To remove users from resources**:

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click **User details** in the **Action** column for the user you want to remove.

3. Select the resource you want to remove the user from by clicking the relevant tab.

4. Click the red icon in the **Remove** column of the resource you want to remove the user from.

<Tip>
  Select **Remove user** from the **Bulk actions** dropdown to remove users from multiple Projects at once.

  <div>
    <img />
  </div>
</Tip>

***

## Groups

Groups are collections of members that are grouped together, allowing them to be added to Projects, Datasets, and Ontologies collectively. User groups are managed on the *Groups* tab of your Workspace settings's dashboard.

<Info>
  Only Workspace admins and [Workforce Managers](/platform-documentation/Annotate/annotate-settings-general#workforce-manager) can create user groups.
</Info>

<div>
  <img />
</div>

### Group Managers and Members

<Note>
  The group managers feature is in BETA. To gain access to the group manager functionality, contact [support](mailto:support@encord.com).
</Note>

User groups consist of **members**, **group managers**, or users who hold both roles.

| Role                 | Permissions                                                                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace Admins** | Can manage all groups and assign group managers.                                                                                                                                              |
| **Group Managers**   | Can add or remove users from their own groups but cannot manage other groups. If the group is added to a Project, the group manager does not automatically inherit the group's assigned role. |
| **Members**          | Can be part of a group but cannot see who the group managers are.                                                                                                                             |

Group managers are useful for overseeing workforces. They can add or remove users from their assigned group without taking on the same user role as their workforce when the group is added to a Project. This allows for flexible team management without unnecessary role restrictions.

<Info>
  Only *Internal* Workspace members can be assigned as group managers.
</Info>

### Create Groups

To create a Group:

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Click **Groups**.

   ![Groups](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-groups-add-04.png)

5. Click **+ Create group**.

   A dialog appears.

6. Give your group a meaningful name and description.

7. Search for and select group members to be included in the group.

8. Click **Add** to add the selected members to the group. Users can be removed by clicking the delete icon next to the user.

9. Click **Next**.

10. Search for and select group managers to be included in the group.

11. Click **Add** to add the selected managers to the group. Group managers can be removed by Workspace admins by clicking the delete icon next to the user.

12. Click **Create group** to create the user group.

### Edit and Delete User Groups

Groups can be edited and deleted on the *Users* tab of your Workspace settings.

**To add users to an existing user group:**

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Navigate to the *Groups* tab of your Workspace settings.

5. Click **Edit** next to the name of the group.

   A dialog appears.

6. Search for and select users to add to the group.

7. Click **Add**.

**To delete users from a user group**:

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Navigate to the *Groups* tab of your Workspace settings.

5. Click **Edit** next to the name of the group.

   A dialog appears.

6. Click the delete icon next to the user.

**To delete a user group:**

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Navigate to the *Groups* tab of your Workspace settings.

5. Click **Edit** next to the name of the group.

   A dialog appears.

6. Click the **Delete group** button.

***

## Project Tags

Project tags serve as a labeling system that helps to categorize, group, and filter Projects within your Workspace. Project tags are created and managed in the *Project tags* tab of the Workspace's dashboard.

<Tip>Project tags are [applied to Projects on the Project level](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags), not from your Workspace dashboard.</Tip>

<Note>The *Project tags* tab is only visible to Workspace Admins, and only Workspace Admins can create Project tags.</Note>

**Create Project Tags**

Project tags must be created before they can be [added to a Project](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags).

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Click **Project tags**.

   ![Add Project tags](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-project-tags-add-04.png)

5. Click **+ New project tag** on the *Project tags* tab.

6. Give the new Project tag a name.

7. Press <kbd>Enter</kbd> to create the tag.

<Note>All Project tag names must be unique.</Note>

**Sort Project Tags**

You can sort Project tags using the *Name*, *Last used by*, *Created by*, and *Projects* columns. Click the sort buttons up to 3 times for various sort options (ascending, descending, and unsorted).

**View Projects with Project tags**

You can directly view the Projects with specific tags by sorting and filtering the Project tags.

**Edit Project Tags**

Double-click a Project tag to change its name. Press <kbd>Enter</kbd> to confirm your selection.

**Delete Project Tags**

To delete a Project tag, click **x** on the Project tag. Deleting a Project tag removes it from all Projects in your Workspace.

***

## Issue Tags

Issue tags serve as a labeling system that helps to categorize, group, and filter issues within Projects. Issue tags are created and managed in the *Issue tags* tab of the Workspace's dashboard.

<Info>Issue tags are [applied to Projects on the Project level](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags), not from your Workspace dashboard.</Info>

<Note>
  The *Issue tags* tab is only visible to Workspace Admins. Only Workspace Admins can create Issue tags in this menu. Project admins can create issue tags [within a Project](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags).
</Note>

<Tip>
  A complete walkthrough of all things Issues and Comments related can be found [here](/end-to-end/Features/issues-e2e).
</Tip>

**Create Issue Tags**

Issue tags must be created before they can be [added to a Project](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags).

1. Click the drop-down at the top of the page after logging in to the Encord Platform.

   ![Workspace access 01](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-01.png)

2. Select the Workspace you want to work with under *Workspaces*.

   ![Workspace access 02](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-02.png)

3. Click **Workspace settings**.

   The *Workspace setings* page appears.

   ![Workspace access 03](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-access-03.png)

4. Click **Issue tags**.

   ![Add Issue tags](https://storage.googleapis.com/docs-media.encord.com/static/img/workspace-settings-issue-tags-add.png)

5. Click **+ New issue tag** on the *Issue tags* tab.

6. Give the new Issue tag a meaningful name.

7. Press <kbd>Enter</kbd> to create the tag.

<Note>All Issue tag names must be unique.</Note>

**Edit Issue Tags**

To edit an Issue Tag, double-click the Issue Tag. When you are done, press <kbd>Enter</kbd> to confirm your changes.

**Delete Issue Tags**

To delete an Issue Tag, click **x** on the Issue tag. Deleting an Issue tag removes it from all Projects in your Workspace.

***

## Activity Center

The *Activity Center* tab monitors your Workspace's activity, providing a detailed view of completed jobs and the users who performed them. The list can be filtered by job type and by job status.

<Tip>Click the **refresh** button to display the most recent jobs and ensure you are viewing the latest activity. </Tip>

### What Activity Can I Track?

The Activity Center displays various job types and their progress. Below is a summary of the available job types:

| **Job Type**   | **Description**                                                     |
| -------------- | ------------------------------------------------------------------- |
| Data import    | Uploading and registering data into the platform.                   |
| Model training | Training a machine learning model using the provided Dataset.       |
| Label import   | Importing labels from external sources for use in annotation tasks. |

In addition to tracking job types, the status column indicates the progress of each job:

* **Processing**: The job is in progress.
* **Success**: The job completed successfully.
* **Error**: An issue occurred processing the job and the job did not complete.

### Actions

The *Action* column displays available actions for each job. For example, in a `Data Import` job, you can click **View folder** to access the storage folder where the data was uploaded. The *Action* column allows you to view error details when a job results in an error.


# Video Tutorials
Source: https://docs.encord.com/platform-documentation/General/video-tutorials



This page contains video tutorials to get you started using the Encord platform. All tutorials can also be found in the relevant sections of the documentation.

## Datasets

<AccordionGroup>
  <Accordion title=" Video Tutorial - Upload Data and Create Datasets ">
    <div>
      <iframe />
    </div>

    See our [documentation on Datasets](/platform-documentation/Annotate/annotate-datasets/annotate-datasets) to learn more.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Creating an AWS integration ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

## Ontologies

<AccordionGroup>
  <Accordion title="Video tutorial - Creating an Ontology">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

See our [documentation on Ontologies](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) to learn more.

## Projects

<AccordionGroup>
  <Accordion title="Video tutorial - Creating a Project">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

***

## Object Primitives & Skeletons

<AccordionGroup>
  <Accordion title="Video tutorial - Creating and using object primitives">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

## Annotation Projects & Templates

<AccordionGroup>
  <Accordion title="Video tutorial - Creating Workflow templates">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Video tutorial - Managing Project collaborators">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Video tutorial - Multiple review stages (Expert review) ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Creating Projects from templates ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Managing tasks (Queue tab) ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Strict review & change review judgment ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Routers ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Exporting labels from Encord">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial -  Creating webhooks ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

## Automation

### Using the Segment Anything Model (SAM)

<AccordionGroup>
  <Accordion title="Video Tutorial - SAM ">
    <div>
      <iframe />
    </div>

    See our [documentation on SAM](/platform-documentation/Annotate/automated-labeling/annotate-sam) for more information.
  </Accordion>
</AccordionGroup>

### Using Interpolation

<AccordionGroup>
  <Accordion title=" Video Tutorial - Interpolation ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Interpolation (DICOM) ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

## Object Primitives / Skeletons

<AccordionGroup>
  <Accordion title="Video Tutorial - Creating and Using Skeletons ">
    <div>
      <iframe />
    </div>

    See our [documentation on creating Object Primitives here](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#object-primitives) to learn more.
  </Accordion>
</AccordionGroup>

## Label Editor

### How To Annotate

<AccordionGroup>
  <Accordion title=" Video Tutorial - Annotating Images ">
    <div>
      <iframe />
    </div>

    See our [Label Editor (Images) documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-images) for more information.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Video Tutorial - Annotating Videos ">
    <div>
      <iframe />
    </div>

    See our [Label Editor (Videos) documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-videos) for more information.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Video Tutorial - Annotating audio ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Video Tutorial - Annotating Text & HTML ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Annotating DICOM">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Working with Bitmasks">
    <div>
      <iframe />
    </div>

    See our [bitmask documentation](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#segmentation-masks--bitmasks) for more information.
  </Accordion>
</AccordionGroup>

### Reviewing Annotations

<AccordionGroup>
  <Accordion title=" Video Tutorial - Reviewing images ">
    <div>
      <iframe />
    </div>

    See our [Label Editor documentation](/platform-documentation/Annotate/annotate-label-editor) for more information.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Reviewing videos ">
    <div>
      <iframe />
    </div>

    See our [Label Editor documentation](/platform-documentation/Annotate/annotate-label-editor) for more information.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Reviewing audio ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Reviewing text / HTML ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

### Label Editor Settings

<AccordionGroup>
  <Accordion title=" Video Tutorial - Label Editor settings ">
    <div>
      <iframe />
    </div>

    See our [Label Editor documentation](/platform-documentation/Annotate/annotate-label-editor) for more information.
  </Accordion>
</AccordionGroup>

### Issues and Comments

<AccordionGroup>
  <Accordion title=" Video Tutorial - Issues and Comments ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

***

## Comparing File Formats in Encord

<AccordionGroup>
  <Accordion title=" Video Tutorial - Comparing images, image groups, and image sequences ">
    <div>
      <iframe />
    </div>

    See our [supported data documentation](/platform-documentation/General/general-supported-data) for more information.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Video Tutorial - Creating & using Dynamic attributes ">
    <div>
      <iframe />
    </div>

    See our [documentation on *Dynamic* attributes](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes) for more information.
  </Accordion>
</AccordionGroup>

## 3D Scene Annotation

<AccordionGroup>
  <Accordion title="In-editor tutorial - Cuboids across time">
    The **Cuboids across time** tutorial is an interactive, 11-step in-editor tutorial (approximately 5 minutes) available in Scene-type (3D LiDAR/point-cloud) Projects. It guides you through the full multi-frame cuboid tracking workflow directly inside the label editor.

    **To access the tutorial:** Open a Scene-type Project in the label editor, click the **Help** button in the top toolbar, select **Tutorials**, then click **Start** on the **Cuboids across time** card.

    The tutorial covers:

    * Selecting and copying a cuboid
    * Pasting the cuboid onto a later frame using `Shift`+click
    * Interpolating between keyframes (`Shift+I`)
    * Viewing the cuboid trajectory
    * Enabling **Auto interpolate** in editor settings
    * Editing the trajectory in grid view
    * Setting the front face on one frame or every frame
    * Toggling a keyframe (`Alt+K`)
    * Locking the cuboid size
    * Marking an object as static (`Alt+S`)

    The tutorial auto-advances each step when the editor detects you have completed the corresponding action. You can re-expand any completed step by clicking its title to re-read the instructions.
  </Accordion>
</AccordionGroup>

## Curation

<AccordionGroup>
  <Accordion title="Video Tutorial - Natural language search ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>


# 2. Set up your Workspace
Source: https://docs.encord.com/platform-documentation/GettingStarted/annotate-getting-started/annotate-setup-workspace



## Users

The **Users** tab of your [Workspace settings](/platform-documentation/General/general-workspace-settings) provides an overview of all your Workspace's users and their user roles.

<div>
  <img />
</div>

### User Roles

Workspaces have several kinds of users. The following table outlines permissions for all user roles.

| Permissions                                            | **Admin** | **Member** | **Workforce Manager** | **Tasker** |
| ------------------------------------------------------ | :-------: | :--------: | :-------------------: | :--------: |
| Add and remove users                                   |     ✅     |      ❌     |     (Only Taskers)    |      ❌     |
| View all Projects, Datasets, and Ontologies            |     ✅     |      ❌     |           ❌           |      ❌     |
| Create Projects, Datasets, and Ontologies              |     ✅     |      ✅     |           ✅           |      ❌     |
| Access Projects, Datasets, and Ontologies (if invited) |     ✅     |      ✅     |           ✅           |      ✅     |
| Create user groups                                     |     ✅     |      ❌     |           ✅           |      ❌     |

<Note>In addition to having a user role within the Workspace, all users have distinct roles in [Projects](/platform-documentation/Annotate/roles-and-permissions#projects), [Datasets](/platform-documentation/Annotate/roles-and-permissions#datasets), and [Ontologies](/platform-documentation/Annotate/roles-and-permissions#ontologies). </Note>

### Adding and Removing Users

<Note>Only Workspace Admins and Workforce managers have the ability to add users to, or remove users from, the Workspace.</Note>

Users belonging to your Workspace are managed on the *Users* tab of your Workspace settings dashboard. The *Users* tab displays by default when you navigate to your Workspace. All users belonging to your Workspace are listed on the *Users* tab.

**To invite new users to your Workspace:**

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click the **+ Invite users** button.
   A dialog appears

<div>
  <img />
</div>

3. Type the email addresses of the users you want to invite.
4. Press <kbd>ENTER</kbd>.
5. Select the role you want the users to have.
6. Click **Add** to invite the users to your Workspace.

<Note>
  Users accept invitations by clicking the email link. The link redirects users to the Encord login page, regardless of whether the user has an existing Encord account.
</Note>

<div>
  <img />
</div>

<Tip>
  Invitations that have not been accepted by the invitee can be resent by clicking the **Resend** button in the **Status** column.
</Tip>

**To remove users from your Workspace or revoke pending invitations:**

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Search for the user you want to remove from your Workspace.

3. Click **User details**

<div>
  <img />
</div>

4. Click **Remove user**.
   If the user being removed is the sole Admin for any Projects or Datasets within the Workspace, you are prompted to select a replacement user from within your Workspace.

<div>
  <img />
</div>

<Note>Admins cannot be removed from a Workspace. To remove an Admin from your Workspace, contact [support@encord.com](mailto:support@encord.com).</Note>

### Status

The user's status shows the status of the invitation to your Workspace. Users can have the following status:

* **Invited**: Shows the date the user was invited to your Workspace. The invitation is pending.
* **Declined**: Shows the date the user declined the invitation to join your Workspace.
* **Joined**: Shows the date the user joined your Workspace.

### Changing User Roles

<Note>
  Only Workspace admins can change user roles in your Workspace.
</Note>

<Warning>
  The roles of Workspace Admins cannot be changed. To change the user role of an Admin, or to remove them from the Workspace, contact [support@encord.com](mailto:support@encord.com).
</Warning>

**To change a user's role within the workspace**:

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Search for the user you want to change the user role for.

3. Click the user role dropdown of the user.

4. Select the role you want the user to have.

<div>
  <img />
</div>

**To change a user's role for a resource**:

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Click **User details** in the **Action** column for the user.

3. Click the user's current role in the Role column, then select the new role you want to assign for the resource.

<Tip>
  Click **Change role** from the **Bulk actions** dropdown to change a user's role in multiple Projects at once.

  <div>
    <img />
  </div>
</Tip>

***

## User Groups

User groups are collections of members that are grouped together, allowing them to be added to Projects, Datasets, and Ontologies collectively. User groups are managed on the *Groups* tab of your Workspace settings's dashboard.

<Info>
  Only Workspace admins and [Workforce Managers](/platform-documentation/Annotate/annotate-settings-general#workforce-manager) can create user groups.
</Info>

<div>
  <img />
</div>

### Group Managers and Members

User groups consist of **members**, **group managers**, or users who hold both roles.

| Role                 | Permissions                                                                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace Admins** | Can manage all groups and assign group managers.                                                                                                                                              |
| **Group Managers**   | Can add or remove users from their own groups but cannot manage other groups. If the group is added to a Project, the group manager does not automatically inherit the group's assigned role. |
| **Members**          | Can be part of a group but cannot see who the group managers are.                                                                                                                             |

Group managers are useful for overseeing workforces. They can add or remove users from their assigned group without taking on the same user role as their workforce when the group is added to a Project. This allows for flexible team management without unnecessary role restrictions.

### Create User Groups

To create a user group:

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Navigate to the *Groups* tab of your Workspace settings.

3. Click **+ Create group**.
   A dialog appears.

<div>
  <img />
</div>

4. Give your group a meaningful name and description.
5. Search for and select group members to be included in the group.
6. Click **Add** to add the selected members to the group. Users can be removed by clicking the delete icon next to the user.
7. Click **Next**.

<div>
  <img />
</div>

8. Search for and select group managers to be included in the group.
9. Click **Add** to add the selected managers to the group. Group managers can be removed by Workspace admins by clicking the delete icon next to the user.
10. Click **Create group** to create the user group.

Groups can be edited and deleted on the *Groups* tab of your Workspace settings.

**To add users to an existing user group:**

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Navigate to the *Groups* tab of your Workspace settings.

3. Click **Edit** next to the name of the group.
   A dialog appears.

4. Search for and select users to add to the group.

5. Click **Add**.

**To delete users from a user group**:

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Navigate to the *Groups* tab of your Workspace settings.

3. Click **Edit** next to the name of the group.
   A dialog appears.

4. Click the delete icon next to the user.

**To delete a user group:**

1. Click **Settings** in the **My workspace** section.
   The Workspace settings page appears with the *Users* tab selected.

2. Navigate to the *Groups* tab of your Workspace settings.

3. Click **Edit** next to the name of the group.
   A dialog appears.

4. Click the **Delete group** button.

### Add Project Tags

Project tags serve as a labeling system that helps to categorize, group, and filter Projects within your Workspace. Project tags are created and managed in the *Project tags* tab of the Workspace's dashboard.

<Tip>Project tags are [applied to Projects on the Project level](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags), not from your Workspace dashboard.</Tip>

<Note>The *Project tags* tab is only visible to Workspace Admins, and only Workspace Admins can create Project tags.</Note>

Project tags must be created before they can be [added to a Project](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags).

**To create Project Tags**:

1. Click **+ New project tag** on the *Project tags* tab.

![Create Project Tag](https://storage.googleapis.com/docs-media.encord.com/static/img/getting-started/projects-project-tags-create.gif)

2. Give the new Project tag a name.

3. Press <kbd>Enter</kbd> to create the tag.

<Note>All Project tag names must be unique.</Note>

### Add Issue Tags

Issue tags serve as a labeling system that helps to categorize, group, and filter issue within Project and Projects themselves within your Workspace. Issue tags are created and managed in the *Issue tags* tab of the Workspace's dashboard.

<Tip>Issue tags are [applied to Projects on the Project level](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags), not from your Workspace dashboard.</Tip>

<Note>
  The *Issue tags* tab is only visible to Workspace Admins. Only Workspace Admins can create Issue tags in this menu. Project admins can create issue tags [within a Project](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags).
</Note>

Issue tags must be created before they can be [added to a Project](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#issue-tags).

**To create Issue Tags**:

1. Click **+ New issue tag** on the *Issue tags* tab.

2. Give the Issue tag a meaningful name.

3. Press <kbd>Enter</kbd> to create the tag.

<Note>All Issue tag names must be unique.</Note>


# Encord's Docs MCP
Source: https://docs.encord.com/platform-documentation/GettingStarted/encord-mcp-setup



<Note>
  This feature is currently in BETA.
</Note>

Connect to Encord's documentation directly from your IDE or AI tool.

<video />

## Intro

Whether you are a developer, an end-user, or an AI app or agent, using Encord's MCP saves you significant time and effort.

We strongly recommend setting up a connection to the MCP for our docs. If you need more proof, have a look at the content from the people who created MCP: [MCP introduction](https://modelcontextprotocol.io/docs/getting-started/intro).

## Setup

Set up connection with the following supported AI assistants:

<Tabs>
  <Tab title="VS Code">
    <Info>
      Prerequisites: VS Code 1.102+ with GitHub Copilot enabled.
    </Info>

    [Click here](vscode:mcp/install?name=encord-docs\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fencord-docs.mcp.kapa.ai%22%7D) to install Encord's MCP extension for VS Code.
  </Tab>

  <Tab title="Cursor">
    [Click here](cursor://anysphere.cursor-deeplink/mcp/install?name=encord-docs\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vZW5jb3JkLWRvY3MubWNwLmthcGEuYWkifQ==) to install Encord's MCP extension for Cursor.
  </Tab>

  <Tab title="Claude CLI">
    Run the following command in your terminal:

    ```
    claude mcp add --transport http encord https://encord-docs.mcp.kapa.ai
    ```

    For more information, see the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
  </Tab>

  <Tab title="ChatGPT Desktop">
    ChatGPT Desktop supports MCP servers in *Developer mode*:

    1. Open ChatGPT Desktop.
    2. Go to **Settings** > **Features**.
    3. Enable **Developer mode**.
    4. Go to **Settings** > **MCP Servers**.
    5. Click **Add Server**
    6. Provide the following:
       * Name: encord
       * URL: `encord-docs.mcp.kapa.ai`

    For more information, see the [ChatGPT Desktop MCP documentation](https://developers.openai.com/api/docs/guides/developer-mode).
  </Tab>

  <Tab title="Claude Desktop">
    **For Team/Enterprise plans**:

    1. An organization admin must first add the connector using [**Admin settings** > **Connectors**](https://claude.ai/settings/connectors) with the URL `https://encord-docs.mcp.kapa.ai`.

    2. Members then add the connector using [**Settings** > **Connectors**](https://claude.ai/settings/connectors).

    3. Restart Claude for the changes to take effect.

    <Note>
      **For Free/Pro plans**: Use the local configuration method (see the **Other** tab) or add the server to your `claude_desktop_config.json` file.
    </Note>

    For more details, see the [Claude Desktop documentation](https://support.claude.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them).
  </Tab>

  <Tab title="Other">
    MCP is an open protocol supported by many clients.

    Use the server URL `encord-docs.mcp.kapa.ai` and refer to your client's documentation for setup instructions.

    Most clients accept the standard MCP JSON configuration format:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "encord": {
          "url": "encord-docs.mcp.kapa.ai"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Using Encord Docs with MCP

After connecting, you can ask questions about Encord from within your editor. For example:

"How do I export labels using the SDK?"

"How do I import data?"

"How do I set up a GCP integration?"


# Merlin - BETA
Source: https://docs.encord.com/platform-documentation/GettingStarted/encord-merlin

Use natural language to explore and act on your Encord data with Merlin.

Merlin is Encord's agentic layer. Use natural language in Encord or a connected AI tool to create projects, define ontologies, check analytics, and more.

<Note>
  Merlin is currently in BETA.
</Note>

## What Merlin can do

Once connected, your AI tools can take actions on your behalf across the Encord platform:

| Category              | What you can ask                                                                                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Projects**          | List your Projects, create new annotation Projects with a chosen Ontology, Dataset (or storage folder), and Workflow, attach an Ontology to an empty Project, and change a Project's status |
| **Ontologies**        | List, create, read, and edit Ontologies — objects, classifications, and nested attributes                                                                                                   |
| **Datasets**          | Browse and search your Datasets                                                                                                                                                             |
| **Folders & storage** | List and create storage folders (including cloud-synced folders), list your cloud integrations, and link a folder to an existing Project                                                    |
| **Workflows**         | List Workflow templates; read and edit a Project's live Workflow graph; view live per-stage task counts; list the tasks in a stage; set or randomize task priorities                        |
| **Editor layouts**    | Configure, read back, and update custom annotation editor layouts for evaluation, rating, and scoring tasks                                                                                 |
| **Analytics**         | Query task throughput, time spent, per-task metrics, and collaborator performance; label quality and label/comment activity broken down by ontology class; plus organization-wide summaries |
| **Documentation**     | Search the Encord documentation and get grounded, cited answers to "how do I…" questions                                                                                                    |
| **Workspaces**        | List the Workspaces you can access and choose which one to work in                                                                                                                          |
| **Feedback**          | File a feature request or bug report directly from a Merlin conversation                                                                                                                    |

## Use Merlin in Encord

When Merlin is enabled for your organization, you can start a conversation from several places in Encord:

* Enter a question in the Merlin box on the home page, or select a suggested prompt.
* Select **Merlin** near the bottom of the navigation sidebar. On the new-chat page, write your own question or choose a starter prompt. The chat sidebar lets you start another chat or return to a previous conversation.
* Open global search and select **Ask Merlin**. If you entered a search term, Merlin opens a conversation and searches for it across your Projects, data, and documentation.

You can continue the conversation in Merlin after entering from the home page or global search.

## Prerequisites

* An Encord account (cloud). Merlin uses OAuth via WorkOS and is not available on on-premises or air-gapped deployments.
* To use Merlin outside Encord, a supported MCP client (see [Connect your AI tools](#connect-your-ai-tools) below).

## Chat with Merlin in Encord

Select **Merlin** in the Encord navigation, then select **New chat** or open a previous conversation. Enter a question in the composer, or select one of the suggested questions to begin.

Merlin streams its response into the conversation and shows its reasoning and tool activity as it works. You can select **Stop** to cancel a response, then send a follow-up message in the same conversation. Conversations are saved automatically and appear in the **Chats** list.

Merlin saves unsent text in your browser, so you can switch chats, navigate to another page, or reload and return to your draft. The **Chats** list marks conversations with unsent text as **Draft**. Text entered in the home-page composer is also available when you open a new chat. Sending the question clears the draft.

<Note>
  The Merlin navigation item is visible only when Merlin is enabled for your organization.
</Note>

## Connect your AI tools

<Info>
  **Choose your region's endpoint.** Merlin is available in two regions. Use the URL that matches where your Encord organization's data is hosted:

  * **EU:** `https://mcp.encord.com/mcp`
  * **US:** `https://mcp.us.encord.com/mcp`
</Info>

<Tabs>
  <Tab title="Claude Code">
    Run the following command in your terminal:

    <CodeGroup>
      ```bash EU theme={"dark"}
      claude mcp add --transport http encord-merlin https://mcp.encord.com/mcp
      ```

      ```bash US theme={"dark"}
      claude mcp add --transport http encord-merlin https://mcp.us.encord.com/mcp
      ```
    </CodeGroup>

    The first time you call a Merlin tool, Claude Code opens a browser to sign in with your Encord account.
  </Tab>

  <Tab title="Claude Desktop">
    **For Team/Enterprise plans:**

    1. An organization admin must first add the connector in [**Admin settings** > **Connectors**](https://claude.ai/settings/connectors) with the URL `https://mcp.encord.com/mcp` or `https://mcp.us.encord.com/mcp`.
    2. Members then add the same connector under [**Settings** > **Connectors**](https://claude.ai/settings/connectors).
    3. Restart Claude Desktop for the changes to take effect.

    **For Individual plans:**

    Add the server to your `claude_desktop_config.json`:

    <CodeGroup>
      ```json EU theme={"dark"}
      {
        "mcpServers": {
          "encord-merlin": {
            "type": "http",
            "url": "https://mcp.encord.com/mcp"
          }
        }
      }
      ```

      ```json US theme={"dark"}
      {
        "mcpServers": {
          "encord-merlin": {
            "type": "http",
            "url": "https://mcp.us.encord.com/mcp"
          }
        }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Claude Web">
    **For Team/Enterprise plans:**

    1. An organization admin must first add the connector in [**Admin settings** > **Connectors**](https://claude.ai/settings/connectors) with the URL `https://mcp.encord.com/mcp` or `https://mcp.us.encord.com/mcp`.
    2. Members then add the same connector under [**Settings** > **Connectors**](https://claude.ai/settings/connectors).
    3. Refresh [claude.ai](https://claude.ai) for the changes to take effect.

    **For Individual plans:**

    1. Go to [claude.ai/customize/connectors](https://claude.ai/customize/connectors).
    2. Click **Add custom connector**.
    3. Paste the server URL above and confirm: `https://mcp.encord.com/mcp` or `https://mcp.us.encord.com/mcp`.
    4. Complete the browser sign-in to authorize access.
  </Tab>

  <Tab title="Cursor">
    [Click here to configure automatically](cursor://anysphere.cursor-deeplink/mcp/install?name=encord\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLmVuY29yZC5jb20vbWNwIn0%3D) to add Merlin to Cursor.

    Or add the following to your Cursor MCP configuration:

    <CodeGroup>
      ```json EU theme={"dark"}
      {
        "mcpServers": {
          "encord-merlin": {
            "type": "http",
            "url": "https://mcp.encord.com/mcp"
          }
        }
      }
      ```

      ```json US theme={"dark"}
      {
        "mcpServers": {
          "encord-merlin": {
            "type": "http",
            "url": "https://mcp.us.encord.com/mcp"
          }
        }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Codex">
    Run the following commands in your terminal:

    <CodeGroup>
      ```bash EU theme={"dark"}
      codex mcp add encord --url https://mcp.encord.com/mcp
      codex mcp login encord
      ```

      ```bash US theme={"dark"}
      codex mcp add encord --url https://mcp.us.encord.com/mcp
      codex mcp login encord
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Other">
    Merlin uses the standard MCP streamable-HTTP transport. Point any MCP-compatible client to:

    <CodeGroup>
      ```EU theme={"dark"}
      https://mcp.encord.com/mcp
      ```

      ```US theme={"dark"}
      https://mcp.us.encord.com/mcp
      ```
    </CodeGroup>

    The client runs an OAuth authorization flow against WorkOS on first use. Every WorkOS-backed login method (SSO, email, etc.) is supported.
  </Tab>
</Tabs>

## Authentication

Merlin authenticates using **OAuth**. When your AI tools first call a Merlin tool, they open a browser window and prompt you to sign in with your Encord credentials. The session is managed by WorkOS. Merlin itself never stores your credentials.

<Info>
  You must sign in as an Encord user whose account was created (or backfilled) after Merlin launched. If your sign-in succeeds but tool calls are rejected, contact your workspace admin.
</Info>

<Info>
  Org-level MFA enforcement is not yet supported for Merlin. Requests from organizations with mandatory MFA will be rejected.
</Info>

## Merlin with Workspaces

If you belong to only one Encord Workspace, Merlin automatically uses that Workspace. No additional setup is required.

If you belong to multiple Workspaces, Merlin needs to know which Workspace you want to work in before it can perform actions for you.

The first time you use Merlin, your AI tools may ask you to choose which Workspace to work in. Your AI tool then works within that Workspace for the rest of the conversation, until you ask it to switch.

To switch Workspaces later, simply tell your AI tools which Workspace you would like to use. Merlin lists your available Workspaces and confirms your selection, and your AI tool works within that Workspace from then on.

Example:

"Show me my available Workspaces."

"Switch my active Workspace to Data Operations."

## Example prompts

Once connected, you can talk to your AI tools naturally. A few examples:

**Setting up a new project end-to-end:**

> "Create an ontology for vehicle detection with bounding box classes for car, truck, and motorcycle. Then create a project called 'Vehicle QA' using that ontology and my existing dataset 'Street Footage'."

**Checking project health:**

> "How many tasks were completed in my 'Pedestrian Detection' project last month, and who were the top three annotators by output?"

**Exploring what's available:**

> "List all my projects that are currently active and show me which ones I'm an admin on."

**Configuring an evaluation workflow:**

> "Set up a custom editor layout on project 'RLHF Round 3' that shows the media and a preference rating question side by side."

**Removing upload-order bias:**

> "Randomize the task order in my 'Pairwise Model Comparison' project so annotators aren't biased by the order files were uploaded in."

**Checking queue state before reassigning work:**

> "How many tasks are currently sitting in the Review stage of my 'Pedestrian Detection' project?"

## Available tools reference

<AccordionGroup>
  <Accordion title="Projects">
    | Tool                         | Description                                                                                                                                                                                                                                  |
    | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `create_project_tool`        | Create an annotation project. Accepts a title, description, ontology, one or more datasets (or a storage folder), and an optional workflow template. Returns a direct link to the new project.                                               |
    | `list_projects_tool`         | List your projects, most recently created first. Supports title search and pagination (50 per page).                                                                                                                                         |
    | `set_project_ontology_tool`  | Attach an ontology to a project that does not yet have one. Switching the ontology of a project that already defines objects or classifications is not supported, to avoid orphaning existing labels. Requires admin or team-manager access. |
    | `update_project_status_tool` | Change a project's status — for example marking it in progress, paused, completed, cancelled, or archived. Requires admin or team-manager access.                                                                                            |
  </Accordion>

  <Accordion title="Ontologies">
    | Tool                   | Description                                                                                                                                                                                                                                        |
    | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `create_ontology_tool` | Create a label taxonomy. Define objects (things to localize, with a shape) and classifications (frame-level questions). Attributes support radio, checklist, text, and numeric types, with radio options supporting up to three levels of nesting. |
    | `get_ontology_tool`    | Read an ontology's current taxonomy so it can be edited. Call this before `update_ontology_tool`, modify the returned tree, then pass it back — keeping each node's `featureNodeHash` unchanged so edits are recognized as the same node.          |
    | `update_ontology_tool` | Edit an existing Ontology. Add, modify, or remove objects, classifications, and attributes, instead of only creating new ones.                                                                                                                     |
    | `list_ontologies_tool` | List your Ontologies, most recently created first, with cursor-based pagination and optional title search.                                                                                                                                         |
  </Accordion>

  <Accordion title="Datasets">
    | Tool                 | Description                                                               |
    | -------------------- | ------------------------------------------------------------------------- |
    | `list_datasets_tool` | List your datasets with optional title/description search and pagination. |
  </Accordion>

  <Accordion title="Folders">
    | Tool                              | Description                                                                                                                                                                                                                                                    |
    | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `list_folders_tool`               | List your storage folders, with optional title search.                                                                                                                                                                                                         |
    | `create_folder_tool`              | Create a new storage folder.                                                                                                                                                                                                                                   |
    | `create_cloud_synced_folder_tool` | Create a storage folder mirrored from a connected cloud storage location (S3, GCS, or Azure) and start an initial scan. Set `auto_sync` to keep it in sync as the bucket changes. Files appear over time, so the folder may look empty briefly after creation. |
    | `list_cloud_integrations_tool`    | List the cloud storage integrations you can access. Use this to find the `integration_hash` for `create_cloud_synced_folder_tool`.                                                                                                                             |
    | `link_folder_to_project_tool`     | Attach a storage folder to an existing project as a dataset — useful when data needs to be added after the project was created, rather than at creation time.                                                                                                  |
  </Accordion>

  <Accordion title="Workflows">
    | Tool                                    | Description                                                                                                                                                                                                                                                                                        |
    | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `list_workflow_templates_tool`          | List all workflow templates, including Encord's built-in templates and your saved custom templates. Use this to find the right template UUID before creating a project that needs a non-default review process.                                                                                    |
    | `get_project_workflow_tool`             | Read a Project's live Workflow graph and settings.                                                                                                                                                                                                                                                 |
    | `set_project_workflow_tool`             | Edit and save a Project's Workflow graph.  Add, remove, or rewire stages after the Project has already been created, rather than only choosing a template up front.                                                                                                                                |
    | `get_project_workflow_task_counts_tool` | Show how many tasks currently sit in each Workflow stage (annotate, review, agent, consensus, complete, and so on). Respects role-based access: managers see counts for every stage, while annotators and reviewers only see counts for stages they can work, capped at the annotator queue limit. |
    | `list_workflow_stage_tasks_tool`        | List the tasks currently in a specific Workflow stage.                                                                                                                                                                                                                                             |
    | `set_task_priorities_tool`              | Set or randomize task priority within a workflow stage. Useful for removing upload-order bias when tasks are otherwise presented in a fixed sequence, such as pairwise comparison projects.                                                                                                        |
  </Accordion>

  <Accordion title="Editor layouts">
    | Tool                               | Description                                                                                                                                                                                                                                                                                                                                 |
    | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `get_project_layout_features_tool` | List the ontology classifications a custom editor layout can reference for a given project. Call this before `set_project_layout_tool` to get the valid `schema_feature_uuid` values.                                                                                                                                                       |
    | `get_project_layout_tool`          | Read back a Project's current custom editor layout.                                                                                                                                                                                                                                                                                         |
    | `set_project_layout_tool`          | Apply a custom annotation editor layout to a project. Supports both classifications and ontology objects, with a `visibleWhen` vocabulary for conditionally showing or hiding elements based on another field's answer. Useful for evaluation, preference rating, and rubric-scoring tasks where the editor functions as a structured form. |

    <Note>
      Switching a project's ontology resets any custom editor layout already applied to that project, since the layout's field references no longer match.
    </Note>
  </Accordion>

  <Accordion title="Analytics">
    Project-scoped analytics tools are available to **project admins and team managers** only. Organization-wide analytics tools are available to **organization admins**, with `organisation_summary_tool` and `organisation_active_projects_tool` self-scoping to your own data if you are not an admin. Time windows default to the last 30 days and cannot exceed 90 days per call — ask your AI tool to chain multiple 90-day windows together for longer ranges.

    | Tool                                     | Description                                                                                                                                                                                         |
    | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `project_throughput_tool`                | Count task actions (completions, approvals, rejections, skips) over a time window. Optional `group_by` splits results by user, day, or workflow stage.                                              |
    | `project_time_summary_tool`              | Total time spent on a project over a time window, broken down by stage, user, or day.                                                                                                               |
    | `project_task_metrics_tool`              | Per-task metrics — one row per task with its media length, time spent, and label create/edit/delete counts, ranked by time spent and paginated (50 per page).                                       |
    | `project_collaborator_performance_tool`  | Rank collaborators by task counts, rejection rate, label activity, and time — for either the annotation or review stage.                                                                            |
    | `project_label_quality_tool`             | Per-ontology-class label quality — submitted, approved, rejected, deleted, and edited counts plus rejection rate, sorted worst-first.                                                               |
    | `project_label_actions_tool`             | Day-by-day label activity — created, approved, rejected, and deleted label counts over the window.                                                                                                  |
    | `project_comment_thread_actions_tool`    | Day-by-day comment-thread (issue) activity — threads created, resolved, reopened, re-rejected, and comments added.                                                                                  |
    | `project_comment_tag_actions_tool`       | Day-by-day breakdown of comment (issue) tags raised, including those created via label rejection.                                                                                                   |
    | `project_comment_tag_by_class_tool`      | Comment (issue) tags broken down per ontology class — which classes attract which kinds of issues.                                                                                                  |
    | `organisation_summary_tool`              | Organization-wide KPIs over a time window (tasks submitted, label instances created/deleted, time spent, files uploaded, and more), each paired with the previous period's value to show the trend. |
    | `organisation_active_projects_tool`      | The organization's most active Projects, ranked by time spent.                                                                                                                                      |
    | `organisation_active_collaborators_tool` | The organization's most active collaborators, ranked by time spent.                                                                                                                                 |
  </Accordion>

  <Accordion title="Documentation">
    | Tool                      | Description                                                                                                                                                                                                                              |
    | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `search_encord_docs_tool` | Search the Encord documentation and get a grounded answer with source links for "how do I…" and product-capability questions about the platform, SDK, and APIs. Use it for how-to questions, not for querying your own projects or data. |
  </Accordion>

  <Accordion title="Feedback">
    | Tool            | Description                                                                                                                                                   |
    | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `feedback_tool` | File a feature request or bug report from within a Merlin conversation. Captures your original prompt alongside the report to help the Encord team triage it. |
  </Accordion>

  <Accordion title="Workspaces">
    | Tool                   | Description                                                                                                                                                                                                                     |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `list_workspaces_tool` | List the Encord Workspaces you have access to. To work in a specific Workspace, your AI tool passes that Workspace's identifier with each subsequent tool call — relevant only for users who belong to more than one Workspace. |
  </Accordion>
</AccordionGroup>

<Note>
  Projects created via Merlin now start in the same active state as projects created through the web app, instead of a transient "setup" state.
</Note>


# Machine-Readable Docs
Source: https://docs.encord.com/platform-documentation/GettingStarted/encord-skillsmd



If you are building autonomous workflows or using an AI assistant to manage your Encord projects, you can inject our platform’s abilities and sitemap directly into your agent’s context.

## Why Use Machine-Readable Docs?

While standard docs are for humans, `llms.txt` and `skill.md` provide a source of truth designed specifically for Large Language Models:

* **Reduce Hallucinations**: Explicit constraints in `skill.md` prevent agents from guessing API parameters or using deprecated methods.
* **Token Efficiency**: We strip away the HTML and UI "noise," saving your context window space and reducing API costs.
* **Complete Site Mapping**: `llms.txt` provides a lightweight index so agents do not have to "crawl" your site to find the right page.
* **Autonomous Action**: Workflow definitions enable agents to actually execute tasks rather than just explain how they might be done.

| File           | The Analogy  | Use Case                                         |
| -------------- | ------------ | ------------------------------------------------ |
| **`llms.txt`** | The Sitemap  | Helping an LLM find the right information.       |
| **`skill.md`** | The Skillset | Helping an agent do work on the Encord platform. |

## Setup

Agents can consume these files in two ways: using a direct URL, or using the Skills CLI.

### The Discovery Index (`llms.txt`)

Point your LLM or RAG system to our documentation index. This file contains a curated list of all pages and their descriptions in a format LLMs can parse instantly.

**URL:** `https://docs.encord.com/llms.txt`

### The Skills CLI (`skill.md`)

For agents that need to understand Encord's specific capabilities and workflows, use the Skills client.

**1. Install the CLI**

```bash theme={"dark"}
npm install -g skills
```

**2. Add Encord's Capabilities**

Run the following command to point your agent to our machine-readable metadata:

```bash theme={"dark"}
npx skills add docs.encord.com
```

## Using skill.md in Production

Traditionally, you write a Python script that calls the Encord SDK to do something specific. For example, to register a Dataset, export labels, and so on. You decide the logic. The script executes it.

An **agent** flips this around. Instead of writing every step yourself, you give an LLM a goal. For example, *"check for any completed label rows and export them to COCO format"*. The LLM then figures out which SDK calls to make, and in what order, to accomplish it. The agent is the LLM acting autonomously on your behalf, writing and executing the logic at runtime rather than ahead of time.

For this to work reliably, the LLM needs accurate knowledge of the Encord platform: what methods exist, what order operations must happen in, what the limits are, and what mistakes to avoid. That is what `skill.md` provides. Without it, the LLM falls back on whatever it learned during training, which may be outdated or just wrong.

<Tip>
  If you are using an LLM as a coding assistant to help you write Encord SDK scripts, you can still benefit from `skill.md`.  Simply paste its contents into your conversation so the LLM generates accurate, production-ready code rather than guessing at method signatures or parameter names.
</Tip>

### Using skill.md in Autonomous Pipelines

`skill.md` is a plain text file. It does nothing on its own. You are responsible for loading its contents into your agent's context before it runs. How you do this depends on the framework you are using, but the principle is the same in all cases: the file's contents need to be present in the LLM's context window when it is deciding what to do.

An example using the Anthropic SDK:

```python theme={"dark"}
import anthropic

with open("skill.md", "r") as f:
    skill_context = f.read()

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    system=f"You are an agent that manages Encord annotation pipelines. Use the following skill reference to guide your actions:\n\n{skill_context}",
    messages=[
        {"role": "user", "content": "Check for any completed label rows in project abc123 and export them in COCO format."}
    ]
)
```

<Tip>
  If you are using a framework like LangChain or CrewAI, inject `skill.md` as a system prompt, a tool description, or a knowledge document depending on what your framework supports. The goal is always the same: make the contents available before the agent starts reasoning about what to do.
</Tip>


# Create Projects
Source: https://docs.encord.com/platform-documentation/GettingStarted/gettingstarted-create-project



Labeling activities are organized and managed in Projects. It brings together Datasets, which store the data to be labeled, and Ontologies, which define the concepts and relationships to be annotated.

## Custom Projects

**To create a new annotation Project**:

1. In the Encord platform, select **Projects** under **Annotate**.
2. Click the **+ New project** button to create a new Project.

<div>
  <img />
</div>

### Project Details

Give the Project a meaningful Project title and description.

<div>
  <img />
</div>

### Add Project Tags

<Note>
  Projects only require a **Title** to be saved.
</Note>

<iframe title="YouTube video player" />

1. Select **Projects** in the Encord platform.

2. Click the **+ New annotation project** button or use <kbd>CONTROL</kbd> / <kbd>CMD</kbd>  + <kbd>ENTER</kbd> to create a new Project.

3. Give the Project a meaningful title and description.

<Note>
  If you are part of an [Workspace](/platform-documentation/General/general-workspace-settings), an optional [Project tags](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#project-tags) drop-down is visible. Project tags are useful for categorizing and finding your Projects. Select as many tags as are relevant for your Project.
</Note>

4. Apply any meaningful [**Project tags**](/platform-documentation/General/general-workspace-settings#project-tags) you need to the Project.

5. Specify the Workflow you want to use for the Project.

6. Click the **Templates** > **Load from template** to use a [Workflow template](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates).

7. Select the template you want to use and click **Load template**.

8. Click the **Ontology** button.

9. Select an [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) from the list, or [create a new Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies) by clicking the **New ontology** button.

10. Click the **Data** button.

11. Select one or more data sources from the list.

12. Click **Collaborators**.

13. Specify the users and the roles they have in the Project.

14. Click **Create project** to finish creating the Project.

<div>
  <img />
</div>

### Workflow

To configure your Workflow, ensure **Workflow** is selected in the Project Configuration.

The Workflow determines how tasks move through your Project from annotation to completion. A simple Workflow containing one Annotation stage and one Review stage is provided by default.

See our documentation on Workflows to:

* Learn how to [customize Workflows](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#creating-workflows).
* Learn how to [create Workflow templates](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates) that can be seamlessly added to any Project you create.

### Data

1. Click the **Data** button.

2. The **Project Data Management** modal opens. Use this modal to browse, preview, and attach data sources to your Project.

3. Select your data source using the tabs in the left panel:
   * **Datasets**: Browse and search available Datasets. Click a Dataset to preview its files in the center panel, then click **Add to project**.
   * **Folders**: Browse and search available storage folders. Click a folder to preview its contents and configure options before adding it.

<Note>
  All files from the folders and Datasets you attach to the Project are available for annotation in the Project.
</Note>

<div>
  <img />
</div>

### Continuous Data Flow

Continuous data flow lets new files added to a folder automatically appear in your Project without manual uploads. This is useful for teams with ongoing data collection pipelines who need their Projects to stay current with incoming data.

You can configure Continuous Data Flow for a folder directly in the **Project Data Management** modal when adding or updating a folder:

* The **Continuous Data Flow** toggle appears in the center panel when you select a folder.
* Enable the toggle to have new files added to the folder automatically enter the Project.
* If you apply a filter, new files pass through that filter before entering the Project.
* The toggle is unavailable when only a subset of folder items is selected. Select all items to enable Continuous Data Flow.

<Note>
  - Only Cloud-synced Folders support Continuous Data Flow. The toggle is unavailable for standard (non-synced) folders.
  - Datasets that already have a backing folder display a **Continuous data flow: On** indicator in the center panel — new files appear automatically without any additional configuration.
</Note>

<div>
  <img />
</div>

After creation, your pipelines appear on the **Continuous Data Flow** tab of the Dataset details page. From here you can review which Cloud-synced Folders are connected to the Dataset and monitor their sync status.

### Ontology

1. Click the **Ontology** button.

2. Browse or search the list of available Ontologies and click an Ontology to select it. The Ontology is highlighted to indicate your selection.

3. Click **Use this ontology** to confirm your selection and attach the Ontology to the Project.

<Tip>
  To preview or edit an Ontology before confirming, switch to the **Edit ontology** (or **View ontology**) tab after selecting it. Return to the **Select ontology** tab and click **Use this ontology** when you are ready to proceed.
</Tip>

<Note>
  If the selected Ontology is used by other Projects, Encord prompts you to confirm the edit before saving any changes, since edits affect all linked Projects.
</Note>

You can also [create a new Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies) by clicking the **+ New ontology** button, if available.

<div>
  <img />
</div>

### Collaborators

Add users to the Project and assign them roles such as Team Managers, Annotators, and Reviewers. As the Project creator, you are automatically assigned the role of Administrator.

<Note>A full list of permissions and user-based access controls can be found [here](/platform-documentation/Annotate/roles-and-permissions#projects). </Note>

1. Click the **Collaborators** button.

2. Start typing the email address of a user you want to add to the Project.

3. Select a role for the user from the drop-down menu.

4. Click **Add to project** to add the user(s) to the Project.

<Tip>You can [add more users and manage all users](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#manage-project-collaborators) after Project creation. </Tip>

<div>
  <img />
</div>

### Create Project

Once you are ready, click the **Create Project** button to finish creating your Project. For documentation on managing and administering your Project see our [documentation here](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects).

<div>
  <img />
</div>

***

## Create from a Template

<iframe title="YouTube video player" />

Templates provide streamlined process to create your Projects with Ontologies, Workflows and Custom Layouts so you can start annotating immediately. Each template can be customized after creation.

<div>
  <img />
</div>

**Create a Project from a Template**:

1. Navigate to **Projects > Project Templates**.
2. Browse or search the available templates.
3. Click a template card. Encord creates the Project automatically and opens the Project **Summary** page with the **Preview** tab active, giving you an immediate visual preview of your new Project.
4. Optionally edit the Project's components to fit your needs.

### Available Templates

<table>
  <thead>
    <tr>
      <th>Template</th>
      <th>Best for</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Video classification</td>
      <td>Tracking scene actors across video with clip-level labels.</td>
      <td>Includes bounding-box tracking of scene actors, with clip-level quality and event-type classifications.</td>
    </tr>

    <tr>
      <td>Pairwise comparison</td>
      <td>Side-by-side evaluation of two outputs.</td>
      <td>Configured for comparing two items and recording a preference or score.</td>
    </tr>

    <tr>
      <td>VLA workflow</td>
      <td>Robotics training data: vision, language, and action labeling.</td>
      <td>Pre-configured for vision-language-action (VLA) labeling. Includes target-object bounding boxes with category and instance attributes, and frame-level action classifications. Suitable for manipulation and navigation tasks.</td>
    </tr>

    <tr>
      <td>Multi-step data extraction</td>
      <td>Structured field extraction from identity documents across multiple review steps.</td>
      <td>Runs extraction across two annotation steps: the first step captures front-of-card identity fields, the second captures back-of-card details. Use this as a pattern for any multi-step document extraction workflow.</td>
    </tr>

    <tr>
      <td>Document annotation</td>
      <td>Text region labeling in documents with entity and sentiment analysis.</td>
      <td>Annotates text regions for sentiment and named entities, plus document-level type and language classifications. Suitable for contracts, reports, forms, and other structured documents.</td>
    </tr>

    <tr>
      <td>Survey</td>
      <td>Collecting structured viewer or reviewer feedback.</td>
      <td>Captures overall impression, free-text feedback, and a recommendation rating in a structured survey format. Use for content review, data quality audits, or preference collection.</td>
    </tr>

    <tr>
      <td>Audio captioning</td>
      <td>Speaker-level transcription and audio quality assessment.</td>
      <td>Annotates audio regions per speaker with a transcript field, and captures an overall audio quality rating. Use for ASR training data, podcast transcription, or audio QA workflows.</td>
    </tr>

    <tr>
      <td>2D object detection with SAM</td>
      <td>Detecting vehicles, pedestrians, and cyclists with scene-level context.</td>
      <td>Provides bounding-box classes for vehicles, pedestrians, and cyclists, along with scene-level classifications for scene type, weather, and time of day. Includes SAM-assisted labeling for faster segmentation. Use as a base for any autonomous driving or smart-city detection Project.</td>
    </tr>

    <tr>
      <td>Real or generated</td>
      <td>Classifying media as authentic or AI-generated.</td>
      <td>Labels media as real or AI-generated, with a confidence rating and multi-select attributes for tell-tale signs (e.g. artifacts, unnatural lighting). Use for content moderation, synthetic data audits, or AI-detection benchmarking.</td>
    </tr>
  </tbody>
</table>


# How to Label
Source: https://docs.encord.com/platform-documentation/GettingStarted/gettingstarted-labeling



Labeling your data is what Encord Annotate is about. Labeling is initiated in the [*Queue* tab of your Project](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-queue-and-workflow). Annotators use the Project's Ontology to label data from Datasets that are attached to the Project.

Three types of annotation can be created:

* **Objects**: Label specific parts of the data unit using a specified shape. Objects are not supported for audio annotation.
* **Classifications**: Apply to a whole image or frame. They do not have a specific location.
* **Attributes**: Can be nested into objects and classifications to add more details to the annotation.

<Tip>For more information on annotation types, see our documentation on [Ontology structure](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies).</Tip>

## Images

<div>
  <iframe />
</div>

***

## Videos

<div>
  <iframe />
</div>

***

## DICOM

<div>
  <iframe />
</div>

***

## Audio

<Warning>
  You can only use *Audio Region* objects, and classifications to label audio files. See our [end-to-end guide on labeling audio files](/end-to-end/Modalities/audio) to learn how to set up audio specific Ontologies.
</Warning>

Navigate to the *Queue* tab of your Project and select the data unit you want to label.

**To label an audio region**:

1. Select a *Audio Region* class from the left side menu.

2. Click and drag your cursor along the waveform to apply the label between the desired start and end points. Repeat this as many times as necessary while the class is selected.

3. If required, apply any attributes to the region.

4. Repeat these steps for as many regions as necessary.

<Tip>
  Audio regions can be copy-pasted using <kbd>CMD</kbd> / <kbd>CTRL</kbd>  + <kbd>C</kbd> and <kbd>CMD</kbd>  <kbd>CTRL</kbd> + <kbd>V</kbd>.
</Tip>

<Tip>When assigning multiple *Audio Region* class labels to the same section of an audio file, hide overlapping labels.</Tip>

<div>
  <img />
</div>

**To apply the classification to the entire audio file**:

<iframe title="YouTube video player" />

1. Select the Classification from the left side menu.

2. For radio buttons and checklists, select the value(s) you want to classification to have. For text classifications, enter the desired text.

### Fill Range to the Playhead

You can quickly snap the boundary of a selected audio classification or audio region range to the current playhead (the visual marker on the timeline or waveform) position using the **Fill to playhead** action. This is useful when you want to extend a range to an exact point without manually dragging the timeline handle.

<Tip>
  Position the playhead at the desired boundary point, select the audio classification/audio region range, then press `Alt+V` (Windows/Linux) or `Option+V` (Mac) to extend the nearest range edge to the playhead. You can also click **Fill to playhead** in the **Available Actions** panel in the left sidebar.
</Tip>

The action automatically determines which edge to move:

* If the playhead is **past the end** of the range, the end boundary extends to the playhead.
* If the playhead is **before the start** of the range, the start boundary extends to the playhead.
* If the playhead is **inside** the range, the action does nothing — it only ever extends a range outward, never trims it.

<Note>
  **Fill to playhead** is only available for editable ranges. The action and hotkey have no effect on read-only or locked ranges.
</Note>

<Tip>
  Use **Fill to playhead** together with the other range-editing shortcuts for fast, keyboard-driven timeline work:

  | Action                          | Windows/Linux     | Mac                  |
  | ------------------------------- | ----------------- | -------------------- |
  | Fill selected range to playhead | `Alt+V`           | `Option+V`           |
  | Expand range right              | `Alt+Right`       | `Option+Right`       |
  | Shrink range right              | `Alt+Left`        | `Option+Left`        |
  | Expand range left               | `Alt+Shift+Left`  | `Option+Shift+Left`  |
  | Shrink range left               | `Alt+Shift+Right` | `Option+Shift+Right` |
</Tip>

***

## Text and HTML Files

<Warning>
  You can only use *Text Region* objects, and classifications to label text files including HTML.
</Warning>

### Text

<div>
  <iframe />
</div>

<AccordionGroup>
  <Accordion title="Labeling Text Files">
    <Tip>
      Use `Ctrl+C` (Windows/Linux) or `Cmd+C` (Mac) to copy the selected text to your clipboard. and Use `Ctrl+V` (Windows/Linux) or `Cmd+V` (Mac) to paste.
    </Tip>

    #### Text

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label text files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-text-doc.gif)
  </Accordion>

  <Accordion title="Labeling JSON Files">
    #### JSON

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label JSON files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-json.gif)
  </Accordion>

  <Accordion title="Labeling XML Files">
    #### XML

    <Warning>*Text Region* objects must be selected at the top of the editor. Only classifications are visible in the left side bar </Warning>

    1. Highlight the text to label.
    2. Click a Text Region label type at the top of the Editor (or use the hotkey) to apply the label.

    ![Label XML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-xml.gif)
  </Accordion>
</AccordionGroup>

### HTML

Encord supports both raw HTML files and single-extension HTML files. The key difference is that single-extension HTML files include all the necessary elements to render the webpage, such as CSS and JavaScript.

<Tip>
  Use `Ctrl+C` (Windows/Linux) or `Cmd+C` (Mac) to copy the selected text to your clipboard. and Use `Ctrl+V` (Windows/Linux) or `Cmd+V` (Mac) to paste.
</Tip>

<div>
  <iframe />
</div>

<AccordionGroup>
  <Accordion title="Labeling HTML - Single Extension">
    #### HTML - Single Extension

    1. Click a *Text Region* label type (or use the hotkey)
    2. Highlight the text you want to apply the label to.

    ![Label HTML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-html-single-extension.gif)
  </Accordion>

  <Accordion title="Labeling HTML - Raw">
    #### HTML - Raw

    1. Click a *Text Region* label type (or use the hotkey)
    2. Highlight the text you want to apply the label to.

    ![Label HTML files with Text Region](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/label_editor/annotate-label-html-raw.gif)
  </Accordion>
</AccordionGroup>

### Using Relation Text Attributes - Text and HTML

Relation text attributes link an object to another object. In images or videos this could be linking a chicken's body to its wing. In PDFs or text documents (text or HTML files) this could be linking words with measurements, or linking words with other words.

<Note>
  Your Ontology must MUST contain text attributes with the Relation feature enabled if you want to use relation text attributes.

  ![Add Relation Text Attribute](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/project-ontologies-text-link.gif)
</Note>

While annotating, you can create a relationship between any object with a relation text attribute and any other object. After you create a relation between objects a workflow arrow points from the object with the relation text attribute to the other object.

![Link objects](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/annotate-project-link-text-region.gif)

***

## Classification Labels

<div>
  <iframe />
</div>

1. Navigate to the *Queue* tab of your Project.

2. Select the data unit you want to label.
   The task opens in the Label Editor.

<div>
  <img />
</div>

3. Select the classification you want to apply to the frame / image from the list of classes on the left side of the Label Editor.

4. Provide a classification answer.
   * **Text classification**: Type the classification answer in the text field that appears.
   * **Radio button**: Select one classification answer from the list of options. Radio buttons can have nested options.
   * **Checklist**: Select all applicable classification answers.

5. If labeling a video, several options appear above the editor timeline.

   * **This frame & save** (hotkey <kbd>Z</kbd>): Apply the classification to the current frame and save.
   * **This frame** (hotkey <kbd>X</kbd>): Apply the classification to the current frame.
   * **Set start to current** (hotkey <kbd>C</kbd>): Defines the current frame as the start of the range to which the classification is applied.
   * **Set end to current** (hotkey <kbd>V</kbd>): Defines the current frame as the end of the range to which the classification is applied.
   * **Add range** (hotkey <kbd>N</kbd>): Applies the classification to the range of frames defined in the bar above the buttons.
   * **Save** (hotkey <kbd>M</kbd>): Saves the classification.

<div>
  <img />
</div>

6. Ensure you save the classification.
   The classification appears in the list of all labels on the left side of the Label Editor.

***

## Object Labels

<Warning>Object labels are not supported for audio files.</Warning>

1. Navigate to the *Queue* tab of your Project.

2. Select the data unit you want to label.
   The task opens in the Label Editor.

3. Select the object you want to label from the list of classes on the left side of the Label Editor.

4. Apply the instance label.

<Tip>We recommend creating automated labels using [SAM](/platform-documentation/Annotate/automated-labeling/annotate-sam) when drawing bounding boxes, bitmasks, and polygons. </Tip>

* **Bounding box**: Click once to start drawing the shape. A second click completes the shape.

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a bounding box ">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

* **Rotatable bounding box**: Click once to start drawing the shape. A second click completes the shape. The box can be rotated.

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a rotatable bounding box">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

* **Polygon**: Click once to start drawing the shape. Click again to add a vertex. Add as many vertices as necessary. To complete the shape, double-click or return to the first vertex.

<AccordionGroup>
  <Accordion title="Watch a tutorial for working with polygons">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

* **Polyline**: Click once to start drawing the shape. Click again to add a vertex. Add as many vertices as necessary. Double-click to complete the shape.

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a polyline">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

* **Keypoint**: Click once to add a keypoint.

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a keypoint">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

* **Bitmask**: Click and hold to draw a bitmask using the brush tool. For detailed information on using bitmasks, see our [documentation here](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#segmentation-masks--bitmasks).

<AccordionGroup>
  <Accordion title="Watch a tutorial for drawing a bitmask">
    <div>
      <iframe />
    </div>
  </Accordion>
</AccordionGroup>

5. Save the label by clicking the **Save** icon on the [editor header](/platform-documentation/Annotate/annotate-label-editor#editor-header).

***

## Adding Attributes

After creating an object or a classification you can add any attributes defined in your [Ontology](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies).

1. In the Labels section of the Label Editor, click the **Edit attributes** button to add an attribute to an object or classification label.

<div>
  <img />
</div>

2. Add an attribute answer.
   * **Text attribute**: Type the attribute answer in the text field that appears.
   * **Radio button**: Select one attribute answer from the list of options. May have nested options.
   * **Checklist**: Select all applicable attribute answers.

<Tip>
  You can select multiple objects, right-click, and select **Add attribute in bulk** to add the same attribute to multiple objects at once.
</Tip>

### Dynamic Attributes

Attributes marked as *Dynamic* can change value over the course of a data unit, and are therefore only applicable to videos, image sequences, and DICOM volumes.

<div>
  <iframe />
</div>

#### Bulk Apply

You can efficiently apply dynamic attributes in bulk to save time and effort. This is accomplished by identifying frames where the attribute changes value as "keyframes," and then applying attribute values between these keyframes.

<div>
  <img />
</div>

1. Apply object labels to **all** relevant frames.

2. Add the [dynamic attribute](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#dynamic-attributes) to the label in the first frame that the object appears in.

3. Navigate to the point of the video or image sequence where the dynamic attribute changes value, and apply the attribute to the object here.

4. Use the **+**, or the keyboard shortcut <kbd>Shift</kbd> + <kbd>L</kbd> to set *keyframes* on frames where the attribute changes value.

5. Use the *Play* icon, or the keyboard shortcut <kbd>Shift</kbd> + <kbd>P</kbd> to apply attribute values to all frames following a *keyframe*, matching the value set in the *keyframe*.

**Apply to new occurrences**:

The *Apply to new occurrences* checkbox in the Label Editor is available for the first instance of a label with a [dynamic attribute](#dynamic-attributes). Selecting this option propagates the attribute to all future instance labels, meaning all labels created for this instance share the attribute value of the initial instance label.

<div>
  <img />
</div>

The 'Apply to new occurrences' functionality also holds for instance labels created automatically using [interpolation](/platform-documentation/Annotate/automated-labeling/annotate-interpolation).

### Relation Attributes

The *Relation* attribute allows you link objects, and specify the relationship between them using text regardless of the annotation type used.

<Note>Only one of the linked objects need a  *Relation* attribute for the objects to be considered linked. For example, consider 2 Ontology objects: a chicken, and a chicken wing. To allow these objects to be linked, a *Relation* attribute must be created for the chicken **or** the chicken wing, while setting up the Ontology. </Note>

All *Relation* attributes must be text fields. They cannot be radio buttons or checklists. *Relation* attributes can be applied to object labels of any kind, but not classifications.

To create a *Relation* attribute, enable the *Relation* feature when creating an attribute during Ontology creation. The default name for all *Relation* attributes is *#relation*.

<div>
  <img alt="Relation Attribute" />
</div>

<Note>Objects are linked in the Label Editor during annotation, not during Ontology creation.</Note>

**Using *Relation* attributes in the Label Editor**:

Once an Ontology with *Relation* attributes has been set up, instances can be linked in the Label Editor during annotation.

1. Create both instance labels.
   For example, a chicken and its wing are labeled using bounding boxes.

2. Click the *Edit attributes* button for the object with the *Relation* attribute.

<div>
  <img />
</div>

3. Click the **Set relation...** bar and select the instance you want to link the selected instance to. In this example the chicken and the wing appear on the same frame, and therefore appear under the *This frame* heading. Instances in different frames appear under the heading *Rest*.

<div>
  <img />
</div>

4. Click **Done**. The instances are now linked.
   This is shown in the *Instance labels* section with the name of the linked instance being displayed.

<div>
  <img />
</div>

***

## Object Primitives & Skeletons

The following tutorial covers creating Object Primitives and labeling using skeletons.

<div>
  <iframe />
</div>

**To label using Skeletons**:

1. Select your Skeleton class from the left-hand menu.
2. Click on the canvas to place points one by one. The currently active point is highlighted in the left sidebar.\
   Once the final point is placed, the Skeleton is automatically completed.

<Info> Alternatively, you can drag and drop the Skeleton onto the canvas and adjust each point individually by dragging them into position. </Info>

3. Use the toggle next to each point to mark it as *visible*, *invisible*, *occluded*, or *self-occluded*. By default, all points are set to ***visible***.

***

## Automated labeling

Encord provides several automated labeling techniques to accelerate your labeling. See our documentation on automated labeling [here](/platform-documentation/Annotate/automated-labeling/annotate-interpolation).


# 1. Your Goals with Encord
Source: https://docs.encord.com/platform-documentation/GettingStarted/gettingstarted-pre-reqs



Before doing anything with Encord you should create goals of what exactly you intend to accomplish with the platform. Your goals inform how best to use Encord.

## Define Your Objectives

To improve your outcomes with Encord, begin by clearly defining your goals. Whether you aim to curate high-quality data, create accurate ground truth annotations, or optimize your model's performance, having clear objectives ensures you leverage the platform effectively. Your goals shape how you use Encord's tools and workflows.

## Data Curation with Encord Index

**Purpose**:

Efficiently curate and organize your data to support downstream activities such as ground truth annotation and model training.

**How it works**:

* Visual Data Exploration: Use Encord Index to browse and group your data items. While effective for small datasets, this approach can become time-intensive for datasets with thousands of units.

* Metadata and Embedding Filtering: Streamline your workflow with native and custom metadata & Embeddings:
  * Native Metadata: Encord automatically embeds your images and frames and calculated metadata, such as brightness, sharpness, uniqueness and more.
  * Custom Metadata: You can import your own user-defined metadata during or after data /registration, type it with a metadata schema, and use it for powerful filtering.

* Automate with the SDK: Once you have explored your data and performed manual curation, you can automate the process with the Collection & Preset SDK.

<Tip>We **STRONGLY RECOMMEND** importing metadata as you register data with Encord. At scale, importing custom metadata when you register your data can save you a significant amount of time.</Tip>

<div>
  <iframe />
</div>

***

## Annotation with Encord Annotate

**Purpose**:

Annotate datasets across diverse modalities (including images, videos, sequences, DICOM, audio, and text) to produce high-quality labeled data for your machine learning applications.

**How it works**:

* Create custom [Workflows](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates) to define who annotates and reviews the data, and establish structured annotation-review processes.

* Create annotations in the [Label Editor](/platform-documentation/Annotate/annotate-label-editor).

* Leverage automation tools to improve speed & accuracy of labeling your data.
  * [SAM 3 Auto-Segmentation and Tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam): Leverage cutting-edge AI tools for fast and precise annotations.
  * [Agents](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview): Automated models that run on your data within Encord — pre-labeling assets, reviewing annotations, or performing custom actions to reduce manual effort and speed up
    your labeling pipelines.

<div>
  <iframe />
</div>

***

## Label Validation and Model Optimization with Encord Active

**Purpose**: Validate labels, assess data quality, and optimize model performance to deliver better results, faster.

**How it works**:

* Label Validation
  * Detect and validate label errors using label, data, and model quality metrics and Encord Embeddings.
  * Apply analytics and custom filtering to identify and correct inaccuracies in labeled datasets.

<div>
  <img />
</div>

* Model Evaluation
  1. Train your model on exported annotations.
  2. Import model predictions into Encord Active.
  3. Use advanced analytics and quality metrics to:
     * Discover weak spots in your model.
     * Improve performance with actionable insights.
     * Leverage embedding plots to visualize model outputs and identify improvement areas.

<Tip>Use custom filtering to refine your data and label exploration, just as in Encord Index, to focus on areas that can enhance your model's performance.</Tip>

<div>
  <img />
</div>


# Welcome to Encord
Source: https://docs.encord.com/platform-documentation/GettingStarted/gettingstarted-welcome



**Jump into the platform with these commonly used pages**

## Data

<Columns>
  <Card title="Supported Data" icon="laptop" href="/platform-documentation/General/general-supported-data">
    Ensure your files are compatible with Encord
  </Card>

  <Card title="Data Integrations" icon="database" href="/platform-documentation/General/annotate-data-integrations">
    Integrate your cloud storage with Encord
  </Card>

  <Card title="Import Cloud Data" icon="cloud" href="/platform-documentation/Curate/add-files/index-register-cloud-data-cloud-sync">
    Register your files with Encord
  </Card>

  <Card title="Data Curation" icon="tags" href="/platform-documentation/Curate/index-getting-started">
    Organize and filter your raw data
  </Card>
</Columns>

## Platform

<Columns>
  <Card title="Annotation" icon="square" href="/platform-documentation/Annotate/annotate-gettingstarted/data-annotation">
    Create precise labels for your data
  </Card>

  <Card title="Export Labels" icon="download" href="/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels">
    Export your Labels
  </Card>

  <Card title="Model Evaluation" icon="bars-progress" href="/platform-documentation/Validation/active-how-to/active-model-predictions-eval">
    Analyze the quality of your labels and models at scale
  </Card>
</Columns>

## SDK

<Columns>
  <Card title="Access Keys" icon="key" href="/platform-documentation/General/general-access-keys">
    Create Access keys to authenticate with the Encord SDK
  </Card>

  <Card title="Register Cloud Data" icon="file-import" href="/sdk-documentation/index-sdk/sdk-upload-data#register-cloud-data">
    Use the SDK to register your files with Encord
  </Card>

  <Card title="Import Labels" icon="download" href="/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual">
    Import existing annotations into Encord
  </Card>

  <Card title="Export Labels" icon="upload" href="/sdk-documentation/sdk-labels/sdk-export">
    Use the SDK to export labels
  </Card>
</Columns>


# Deployment Options & Requirements
Source: https://docs.encord.com/platform-documentation/Other/deployment-options



<Note>
  On Premise deployment options are only available to Enterprise customers.
</Note>

<Note>
  In on-premise deployments, the Encord Platform operates in complete isolation and does not interact with external Encord infrastructure.
</Note>

## Deployment Options

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Pros</th>
      <th>Cons</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Cloud</td>

      <td>
        <ul>
          <li>Ready to start on day 1 (no initial & on-going configuration required)</li>
          <li>Inexpensive and no maintenance required for client</li>
          <li>Secure (SOTA encryption, data resides client-side, etc.)</li>
        </ul>
      </td>

      <td>
        <ul>
          <li>May not be appropriate for classified environment data restrictions</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Virtual Private Cloud (VPC)</td>

      <td>
        <ul>
          <li>Compatible with GCP/Azure/AWS</li>
          <li>Higher level of control over application accessibility</li>
          <li>May fulfill classified and highly sensitive data restrictions</li>
        </ul>
      </td>

      <td>
        <ul>
          <li>Client to maintain hardware compatibility and software versioning</li>
          <li>Requires in-house Kubernetes expertise</li>
          <li>No real-time software updates</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>On-Premise</td>

      <td>
        <ul>
          <li>May fulfill classified and highly sensitive data restrictions</li>
        </ul>
      </td>

      <td>
        <ul>
          <li>Client to maintain hardware compatibility and software versioning</li>
          <li>Requires in-house Kubernetes expertise</li>
          <li>No real-time software updates</li>
          <li>Expensive to set up and maintain</li>
          <li>Client has to procure hardware and maintain network setup</li>
          <li>Network and app security maintained by client</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

***

## Deployment Requirements

<table>
  <thead>
    <tr>
      <th>Deployment Option</th>
      <th>Setting up OS and Encord App</th>
      <th>Management and Monitoring</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Cloud</td>
      <td>None required</td>
      <td>Standard cloud support</td>
    </tr>

    <tr>
      <td>Virtual Private Cloud (VPC)</td>

      <td>
        <ul>
          <li>Terraform for rolling out environment</li>
          <li>Ansible installation script for packages</li>
          <li>Kustomize scripts for deployments</li>
        </ul>
      </td>

      <td>
        <ul>
          <li>Monitoring setup</li>
          <li>Remote support</li>
          <li>Upgrade rollouts</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>On-Premise</td>

      <td>
        <ul>
          <li>Based Installation Setup (RAID + OS)</li>
          <li>Ansible installation script for packages</li>
          <li>Kustomize scripts for deployments</li>
        </ul>
      </td>

      <td>
        <ul>
          <li>Monitoring setup</li>
          <li>Remote support</li>
          <li>Upgrade rollouts</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>


# Egress Costs
Source: https://docs.encord.com/platform-documentation/Other/egress-costs



Egress costs refer to the fees incurred when data transfers out of a cloud provider's storage to another location. For example, to a user's browser or a processing server. When using Encord, egress costs arise when media files are accessed for annotation, display, or computation.

To minimize these costs, Encord optimizes data transfers by:

* Allowing users to register media with metadata and embeddings, avoiding unnecessary file ingestion.
* Performing searches on metadata instead of the actual media files.
* Streaming only the visible portions of videos and thumbnails.
* Utilizing local caching to prevent repeated data transfers during annotation.

<Tip>
  Local caching prevents repeated egress costs when revisiting the same section of a video during annotation.
</Tip>

| **Scenario**                     | **Egress Cost Impact**                                                                                                                                                                    |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data Registration**            | No egress cost if users provide media metadata and embeddings, as files are not ingested. If metadata is not provided then Encord downloads the data once for processing.                 |
| **Searching**                    | Searches are performed on metadata stored in Encord's servers, incurring no egress cost.                                                                                                  |
| **Search Results**               | Data is streamed only for thumbnails in view; for videos, only visible frames are loaded.                                                                                                 |
| **Video Annotation**             | Egress costs apply only to the section of the video being viewed/annotated, with some buffering allowance. Local caching prevents repeated egress costs when revisiting the same section. |
| **Index/Active Display**         | Minimal egress cost, as filtering is based on precomputed metrics/embeddings.                                                                                                             |
| **Visual Curation in Active**    | Small data transfer since only selected frames are displayed.                                                                                                                             |
| **Metric/Embedding Computation** | If processed on Encord's side, egress cost equals the data size. Needs confirmation on frame ingestion. No egress cost if users provide media metadata and embeddings.                    |
| **Cost**                         | 1GB of 1080p footage costs \~\$0.10 in egress.                                                                                                                                            |


# Single Sign On (SSO) support
Source: https://docs.encord.com/platform-documentation/Other/encord-sso



Encord supports Single Sign On (SSO) for [Enterprise customers](https://encord.com/pricing/). [Contact our sales team](https://encord.com/contact-us/) to upgrade to the Enterprise price plan and set up SSO.

## What is SSO?

Single Sign-On (SSO) is an authentication mechanism that enables users to access multiple applications and services with a single set of login credentials. This eliminates the need for users to remember and enter separate usernames and passwords for each system, enhancing user experience and security.

[Contact our sales team](https://encord.com/contact-us/) to upgrade to the Enterprise price plan and set up SSO.

***

## Requirements

To integrate SSO, you must have an identity provider (for example Microsoft or JumpCloud) that supports either [SAML](https://www.cloudflare.com/en-gb/learning/access-management/what-is-saml/) or [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/).

***

## Log in with SSO

1. Enter your company email on the Encord login page [https://app.encord.com/login](https://app.encord.com/login) or [https://app.us.encord.com/login](https://app.us.encord.com/login).
   If SSO is enabled you are automatically logged in.

<Info>User is automatically added to the company Workspace in Encord.</Info>


# Rendering Geospatial Imagery
Source: https://docs.encord.com/platform-documentation/Other/geospatial-guidelines



For best results when working with geospatial imagery in Encord, follow these steps:

1. **Choose the right image format**
   Before uploading images to datasets, it's crucial to convert them to either PNG or JPEG formats. These formats are widely supported by web browsers, ensuring compatibility across different platforms.

2. **Trim images**
   If an image requires trimming, we recommend that the dimensions of the trimmed image don't exceed a limit of 2500x2500 pixel, to ensure a smooth rendering experience. This limit can be adjusted according to internet speeds, with lower speed requiring smaller pixel dimensions to ensure a smooth experience.

3. **Use image groups for quality**
   In scenarios where preserving image quality at the pixel level is crucial, consider using image groups instead of image sequences, since creating image groups does not affect the image quality in any way.

4. **Handling images with a high dynamic range**
   It is important to preprocess images with bands that have a high or extended dynamic range (HDR), so that these images fit within the \[0, 255] range. This ensures consistency when viewing images in the Label Editor.

5. **Match band count to channels**
   Ensure that the number of bands in the image files matches the specified number of channels.   If files don't meet this requirement, they must be preprocessed to match the expected band count.
   * For Synthetic Aperture Radar (SAR) or Grayscale images the value will be 1.
   * For True or False color composites the value will be 3.

6. **Group multi-band images**
   If you have a multi-band image and want to display various band combinations, we recommended combining into a single [image group](/platform-documentation/General/general-supported-data#image-groups). This allows you to view and select different band combinations with ease.

7. **Upload and manage metadata**
   Upload or attach preprocessed images to a dataset and save their metadata in the corresponding `DataRow.client_metadata` field when accessing them via the SDK. Remember that metadata can be added at any time, even after uploading the data to a dataset.

8. **Explore geospatial data interactively**
   The Geospatial Explorer map view supports interactive cluster navigation. Click a cluster on the map to automatically apply a geospatial bounding-box filter that narrows the view to that cluster's geographic area. Continue clicking clusters to progressively drill down into smaller regions. Once the filtered view contains 1,000 or fewer items, the map switches from clustered buckets to individual data points. Click any individual point to open the Item Preview modal for that item.

   <Note>The **Show Similar**, **View Next**, and **View Previous** actions in the Item Preview modal are not available in the map context. Map viewport controls and the style picker are hidden while the Item Preview modal is open.</Note>

   For full details on using the interactive map view, see the [Geospatial Map View](/platform-documentation/Curate/index-map-view) documentation.

9. **Select a geographic region using Box Select**
   The Geospatial Explorer map view provides two interaction modes, selectable from the toolbar that appears below the geocoder search box in the top-left corner of the map:

   * **Pan & click** (`C`) — the default mode. Pan the map and click individual points to open them.
   * **Box select** (`B`) — drag to draw a rectangular selection on the map. The cursor changes to a crosshair, and a blue bounding-box outline appears as you drag and persists after you release.

   After completing a box selection, a **Zoom into selection** button (filter icon) appears at the corner of the selection box. Click it to apply the rectangle as a persistent geospatial filter and zoom the map to fit the selected area. Press `Escape` to clear the current selection without applying it.

   <Note>The interaction mode toolbar only appears when a geospatial metadata key is configured for your Project. Keyboard shortcuts (`C` and `B`) are disabled when a modal is open or when focus is in the geocoder search field.</Note>

10. **Switch map background styles in the Geospatial Explorer**
    When exploring geospatial data in the Geospatial Explorer map view, use the **Map / Satellite / Terrain** style picker in the bottom-right corner of the map to change the background style:

* **Map** — displays a standard vector map (respects your dark or light mode setting).
* **Satellite** — displays satellite imagery with street overlays.
* **Terrain** — displays a topographic/outdoors style.

Your camera position (location, zoom level, bearing, and pitch) and any drawn rectangle selections are preserved when you switch between styles. The style resets to **Map** each time you reload the page.

<Note>The Geospatial Explorer opens in **Pan & click** mode by default, so you can pan and interact with the map immediately without needing to switch modes first.</Note>

<Tip> Encord strongly recommends using the Chrome web browser when working with the Label Editor for the best experience.</Tip>


# Vulnerability Disclosure
Source: https://docs.encord.com/platform-documentation/Other/vulnerability-disclosure



## How to Submit a Vulnerability

Email vulnerability reports to Encord's Product Security Team at [security@encord.com](mailto:security@encord.com).

## What We Prioritize

To help us triage and resolve your report effectively:

* **Well-written reports in English** have a higher probability of resolution
* **Proof-of-concept code** equips us to better understand and triage the vulnerability
* **Clear context**: Explain how you found the bug, its impact, and potential remediation steps
* **Disclosure plans**: Let us know if you have any public disclosure timeline or intentions

Lower priority may be given to reports that include only crash dumps or automated tool output, or vulnerabilities outside our initial scope.

## What You Can Expect From Us

* **Response within 2 business days** to acknowledge receipt
* **Transparent communication** on expected timeline and any challenges that may extend it
* **Stage notifications** as the vulnerability progresses through our review process
* **Open dialog** to discuss the issue
* **Credit** once the vulnerability has been validated and fixed

If we encounter communication issues or other obstacles, we may bring in a neutral third party to help resolve how best to proceed.


# Bulk Actions
Source: https://docs.encord.com/platform-documentation/Validation/active-basics/active-bulk-actions



You can apply bulk changes to the labels and frames in a Project directly from the **Explore** tab. In each case you select the items you want to change, open the **Actions** menu, and choose an action. The label operations **Change class**, **Edit attributes**, and **Delete labels**, and **Bulk classify** are grouped under **Edit labels** in that menu. Every bulk action applies to the items you select, or to the entire filtered set when you choose **Select all**.

<Tip>With items selected, press **A** to open the Actions menu. The menu is searchable, and each action shows its own keyboard shortcut inline that you can use while the menu is open.</Tip>

## Change Object Class

Change the object class assigned to selected objects. In the Actions menu, under **Edit labels**, this action appears as **Change class**.

<Note>You can only change an object to another class of the same object type. For example, bounding box to bounding box, or bitmask to bitmask.</Note>

<Warning>Changing an object's class removes all attributes on the selected object classes.</Warning>

**To change object classes:**

1. Log in to the Encord platform.

2. Go to **Projects** > **\[select a Project]** > **Explore**.

3. Switch to the **Labels** view and filter to the objects you want.

4. Select the objects you want to update, or click **Select all** to include the entire filtered set.

5. Click **Actions** in the selection toolbar, or press **A**.
   The Actions menu appears, with the label operations grouped under **Edit labels**.

6. Select **Change class**.
   The *Edit Object Class* dialog appears.

7. Under **Classes to change**, select the object classes you want to change.

8. Under **Change to**, select the class you want to change them to.

9. Click **Initiate Bulk Edit Object Class**.
   Encord runs the change as a bulk job across your selection.

## Edit Object Attributes

Update the attribute answers on selected objects of one class. In the Actions menu, under **Edit labels**, this action appears as **Edit attributes**.

<Info>Attributes you leave alone keep their current answers. Setting a checklist replaces the whole answer. The options you tick become the answer, and any you leave unticked are removed.</Info>

**To edit object attributes:**

1. Log in to the Encord platform.

2. Go to **Projects** > **\[select a Project]** > **Explore**.

3. Switch to the **Labels** view and filter to the objects you want.

4. Select the objects you want to update, or click **Select all** to include the entire filtered set.

5. Click **Actions** in the selection toolbar, or press **A**.
   The Actions menu appears, with the label operations grouped under **Edit labels**.

6. Select **Edit attributes**.
   The *Edit Object Attributes* dialog appears.

7. Select the object class whose attributes you want to edit.

8. Enter the new attribute answers (text, number, radio, or checklist).

9. Click **Initiate Bulk Edit Object Attributes**.
   Encord applies the answers to matching objects of the selected class across your selection.

## Bulk Classify

Apply a Classification, and its attribute answers, to selected images or frames. In the Actions menu, under **Edit labels**, this action appears as **Bulk classify**. Bulk classify runs as an asynchronous job, and you are notified when it completes.

<Note>The Classification you apply must already exist in an Ontology included in your Project. You can create an Ontology that includes Classifications from the [Encord platform](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies) or [using the Encord SDK](/sdk-documentation/ontologies-sdk/ontologies).</Note>

**To bulk classify images or frames:**

1. Log in to the Encord platform.

2. Go to **Projects** > **\[select a Project]** > **Explore**.

3. Switch to the images/frames view and filter to the items you want. Depending on your Project's media, this tab is labeled **Images**, **Frames**, or **Images & Frames**.

4. Select the items you want to classify, or click **Select all** to include the entire filtered set.

5. Click **Actions** in the selection toolbar, or press **A**.
   The Actions menu appears, with the operations grouped under **Edit labels**.

6. Select **Bulk classify**.
   The *Bulk Classify* dialog appears.

7. Select a Classification from the dropdown.

8. Set the Classification's attribute answers in the tree below the dropdown.

9. OPTIONAL: Turn on **Override existing classification** to replace any existing Classification of the same type on the selected items, then confirm the override when prompted.

   <Warning>Overriding deletes and replaces the existing Classification on the selected items and cannot be reverted.</Warning>

10. Click **Initiate Bulk Classify Job**.
    Encord runs the classification as a bulk job. You are notified when it completes.

## Delete Labels

Permanently delete all labels on the selected items. In the Actions menu, under **Edit labels**, this action appears as **Delete labels**.

<Warning>Deleting labels **permanently deletes** all labels on the selected items and **CANNOT BE UNDONE**.</Warning>

<Tip>We recommend saving a version of your labels before you delete them. See [Save Label Version](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#save-label-version).</Tip>

**To delete labels:**

1. Log in to the Encord platform.

2. Go to **Projects** > **\[select a Project]** > **Explore**.

3. Switch to the **Labels** view and filter to the labels you want.

4. Select the labels you want to delete, or click **Select all** to include the entire filtered set.

5. Click **Actions** in the selection toolbar, or press **A**.
   The Actions menu appears, with the label operations grouped under **Edit labels**.

6. Select **Delete labels**.
   The *Bulk Delete all Labels* dialog appears.

7. Review the warning. If you want a backup, save a label version before proceeding.

8. Click **Delete ... labels forever** (the button shows the number of labels selected).

9. When prompted to confirm, click **Proceed to Delete**.
   Encord deletes the labels as a bulk job.


# Label Collections
Source: https://docs.encord.com/platform-documentation/Validation/active-basics/active-collections-labels



Collections are created by tagging/labeling images and then building groups (Collections) based on the tagged images. Tagging is a versatile feature used in almost all Encord workflows, whether you are relabeling, augmenting, exporting, or deleting data.

<Note>
  Users with the **Viewer** role on Workflow Projects can access the Explorer and filter by existing collections, and collection tags remain visible on items in the item preview. However, Viewers cannot create, edit, delete, or convert collections, and the options to add or remove items from a collection are hidden. All other collection management actions — including bulk classify, send to annotate, and add to dataset — are also hidden for Viewers. For the full permissions matrix, see [Roles and permissions](/platform-documentation/Annotate/roles-and-permissions).
</Note>

Label Collections consist of groups of image/video/audio files that have object or classification labels applied to them. The Collection focus is on labels. For example, you want to create a Collection of data units that have specific object or classification labels applied to them (data units with labels `blueberries` or `cherries`).

In Encord, creating Collections provides several advantages:

* **Organization**: Allows you to organize your data effectively within the platform. By assigning Collection tags to your data points, you can group and categorize data based on common characteristics, making it easier to manage and navigate large subsets of the dataset.

* **Enhanced search and filtering**: Collections in Encord enable powerful search and filtering capabilities. You can search for specific data points or filter data based on tags, narrowing down your focus to the relevant information you need.

* **Customizable metadata**: Collection tags serve as customizable metadata that can provide additional context and information about your data. You can define and assign tags that align with your specific project requirements, providing meaningful insights and annotations for efficient data analysis.

* **Collaboration and knowledge sharing**: Tagging promotes collaboration and knowledge sharing among team members in Encord Active. With consistent tagging conventions, team members can easily understand and access tagged data, facilitating efficient collaboration and ensuring everyone is on the same page.

* **Performing bulk actions**: Tagging allows the performing of bulk actions on groups of data units or labels. For example, you can modify data units with incorrect labels at the push of a button.

These are just a few of the advantages of tagging in Encord, and there may be more benefits specific to your project and workflow.

**To create a Label Collection:**

1. Navigate to **Projects** and click the Project.

2. Open the **Explore** tab of the Project.

3. Select **Labels**.

   ![Label Collections](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-collections-labels.gif)

4. Search, sort, and filter your labels until you have the subset of the data you need.

5. Select one or more of the images.
   A ribbon appears at the bottom of the Explorer workspace.

6. Click **Select all** to select all the images in the subset.

7. Click **Add to a Collection**.

8. Click **New Collection**.

9. Specify the Collection type as **Label**.

10. Specify a meaningful title and description for the Collection.

    <Note> The title specified here applies as a tag/label to every selected image.</Note>

11. Click **Collections** to verify the Collection appears in the Collections list.

## Collection actions menu

Each collection in the Explorer filter panel has a **...** (horizontal dots) button that opens a collection actions submenu. This submenu provides quick access to collection-specific actions without leaving the Explorer.

### Collection ID

The submenu header displays the collection name in bold at the top, with the collection's unique ID shown beneath it. Click the copy icon next to the ID to copy it to your clipboard.

<Tip>Use the copied collection ID for API calls, support requests, or cross-referencing collections across your workflow.</Tip>

<Note>The copyable collection ID and grouped actions menu described here apply only to the **...** submenu in the Explorer filter panel. The collections table row menu is unchanged.</Note>

### Grouped actions

Actions in the submenu are organized into sections separated by dividers, making it easier to find the right action:

* **Navigate** — Go to the collection in Explorer.
* **Manage** — Edit collection details.
* **Data** — Add to a dataset or download a CSV.
* **Workflow** — Task actions, bulk classify, convert collection, edit object class, and edit object attributes (available for Project domains only).
* **Danger** — Delete the collection.

Encord automatically hides sections with no available actions for your current context, so you only see relevant options.


# Issues and Comments
Source: https://docs.encord.com/platform-documentation/Validation/active-basics/active-comments



Issues and comments provide a way to communicate with Annotators, Reviewers, Annotators & Reviewers, Team Managers, and Admins within Annotation projects and Active projects.

Issues and Comments are supported across Annotate and Active, meaning [issues created in Annotate](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#issues-and-comments) can be seen in Active, and issues create in Active can be seen in Annotate.

<Note>Users with the Viewer role on Workflow projects can post comments and raise issues in the Explorer. This is an explicit exception to their otherwise read-only access — Viewers cannot create or modify collections, filter presets, or prediction sets, and cannot perform bulk actions.</Note>

## Add comments in Active

Issues and comments in Active can be added to individual frames within a Project or to all frames within a Collection.

<AccordionGroup>
  <Accordion title="To add issues / comments to an individual frame in Active:">
    1. Log in to the Encord platform.
       The Encord UI appears.

    2. Click **Active**.
       The Active home page appears with all available Projects appearing in the home page.

       <Note>If no Projects appear on the Active home page, import a Project from Annotate.</Note>

    3. Click a Project.
       The Project workspace appears with the *Explorer* page displaying.

    4. Filter, sort, and search for the frame/image you want to add comments to.

    5. Mouseover the image you want to add a comment to.
       A few actionable icons appear.

       ![Add Comment to Frame](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-comment-add-to-frame.gif)

    6. Click the Expand image icon.
       A larger view of the image appears.

    7. Click **Comments**.
       The *Comments* tab appears.

    8. Provide a comment.

    9. Add/remove the frame/image to/from a Collection.

    10. View the frame/image in Annotate.

    11. Perform a similarity search on the image/frame.

    12. Add comments to other frames/images as needed.

    13. Add those frames/images to the Collection.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="To add issues / comments to a Collection:">
    Comments made when sending a Collection to Annotate appear in every frame in a Collection.

    1. Log in to the Encord platform.
       The Encord UI appears.

    2. Click **Active**.
       The Active home page appears with all available Projects appearing in the home page.

       <Note>If no Projects appear on the Active home page, import a Project from Annotate</Note>

    3. Click a Project.
       The Project workspace appears with the *Explorer* page displaying.

    4. [Create a Collection](/platform-documentation/Curate/curation-basics#collections).

       ![Create Comment for Collection](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-comments-add-to-collection.gif)
  </Accordion>
</AccordionGroup>

## View Annotate Issues in Active

To view issues created in Annotate, you must sync the Annotate Project data to Active.

<AccordionGroup>
  <Accordion title="To view Annotate issues in Active:">
    1. Log in to the Encord platform.
       The Encord UI appears.

    2. Click **Active**.
       The Active home page appears with all available Projects appearing in the home page.
       ![Sync Annotate Project data to Active](https://storage.googleapis.com/docs-media.encord.com/static/img/active/user-guide/active-sync-project-data.png)

    3. Mouseover the Project.
       The More **...** icon appears.

    4. Click the More **...** icon.
       A menu appears.

    5. Click **Sync Project Data**.
       All the Annotate Project data (including comments) syncs to the Project in Active.
  </Accordion>
</AccordionGroup>


# Shortcuts and Prediction Types
Source: https://docs.encord.com/platform-documentation/Validation/active-basics/active-issue-shortcuts-prediction-types



Overview shortcuts for Data, Labels, and Predictions and Prediction Types for Predictions, give you a quick method to filter your unwanted or problematic images. They are shortcuts to improving datasets and model performance. They give you a quick launch pad to improve your data and your model performance.

<Note>The overview shortcuts for Data, Labels, and Predictions in the *Overview* tab are generalized. Contact us if you want personalized shortcuts populating the *Overview* tab.</Note>

## Data Issue Shortcuts

![Data Shortcuts](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-shortcuts-data.gif)

**Data Issues Overview**

| Title                                                                                                                                  | Metric Type | Ontology Type |
| -------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------- |
| **Duplicates** -  Duplicate and near-duplicate images. Images with a **Uniqueness** score of 0.0 to 0.00001 are flagged as duplicates. | `image`     |               |
| **Blur** - Images that are too blurry. Images with a **Sharpness** score of 0.0 to 0.005 are flagged as blurry.                        | `image`     |               |
| **Dark** - Images that are too dark. Images with a **Brightness** score of 0.0 to 0.1 are flagged as too dark.                         | `image`     |               |
| **Bright** - Images that are too bright. Images with a **Brightness** score of 0.7 to 1.0 are flagged as too bright.                   | `image`     |               |

## Label Issue Shortcuts

![Label Shortcuts](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-shortcuts-labels.gif)

**Label Issues Overview**

| Title                                                                                                                                                                                          | Metric Type | Ontology Type                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| **Aspect Ratio** - Identifies objects with a low aspect ratio value. Images with an **Aspect Ratio** score of 0.0 to 0.1 are flagged as having an issue.                                       | `image`     | `bounding box`, `polygon`, `rotatable bounding box`                                  |
| **Border Proximity** - Identifies annotations that are too close to image borders. Images with a **Border Proximity** score of 1 are flagged as being too close to the border.                 | `image`     | `bounding box`, `point`, `polygon`, `polyline`, `rotatable bounding box`, `skeleton` |
| **Low Annotation Quality** - Compares image classifications against the 60 most similar images. Images with a **Classification Quality** score of 0.0 to 0.02 are flagged as having an issue.  | `image`     | `radio`                                                                              |
| **Relative Area** - Identifies annotations that are relatively too small compared to the size of the image. Images with a **Relative Area** score of 0.0 to 0.003 are flagged being too small. | `image`     | `bounding box`, `polygon`, `rotatable bounding box`                                  |

## Viewer Role Access

Users with the Viewer role on Workflow Projects can access the **Explore** tab and browse the Explorer in read-only mode. Viewers can use the grid, analytics, and embeddings views, and apply existing filters — but Encord hides all mutation controls for Viewers.

The following actions are not available to Viewers in the Explorer:

* Bulk actions (priority, collections, bulk classify, change class, delete labels, export CSV)
* Collection management (create, edit, delete, convert, send to Annotate, bulk classify, add to dataset)
* Adding or removing items from collections in the item preview (collection tags remain visible)
* Creating, editing, deleting, or saving filter presets (the `Alt+P` shortcut is also disabled)
* The prediction set **Manage** button (import/delete)

Viewers can still post comments and raise issues in the Explorer.

<Note>The Explore tab is not available to Viewers on ManualQA Projects. This applies to Workflow Projects only.</Note>

For the full role permissions matrix, see [Roles and Permissions](/platform-documentation/Annotate/roles-and-permissions).

## Prediction Issues and Types

![Predictions Shortcuts](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-shortcuts-predictions.gif)

**Prediction Issues Overview**

| Title                                                                                                                                                                          | Metric Type | Ontology Type                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------ |
| **Shape Outliers** -  Duplicate and near-duplicate images. Images with a **Polygon Shape Anomaly** score of 0.0 to 0.02 are flagged as duplicates.                             | `image`     |                                                                                      |
| **Border Proximity** - Identifies annotations that are too close to image borders. Images with a **Border Proximity** score of 1 are flagged as being too close to the border. | `image`     | `bounding box`, `point`, `polygon`, `polyline`, `rotatable bounding box`, `skeleton` |
| **Aspect Ratio** - Identifies objects with a low aspect ratio value. Images with an **Aspect Ratio** score of 0.0 to 0.1 are flagged as having an issue.                       | `image`     | `bounding box`, `polygon`, `rotatable bounding box`                                  |

**Prediction Types**

| Title                                                                                                          | Metric Type | Ontology Type |
| -------------------------------------------------------------------------------------------------------------- | ----------- | ------------- |
| **All** -  All model outcomes.                                                                                 | `image`     |               |
| **All Positives** - All model outcomes that are True Positive and False Positive.                              | `image`     |               |
| **True Positives** - All model outcomes where the model correctly identified objects.                          | `image`     |               |
| **False Positives** - All model outcomes where the model incorrectly identified objects as the correct object. | `image`     |               |
| **False Negatives** - All model outcomes where the model incorrectly identified objects as the wrong object.   | `image`     |               |

## Use Issue and Prediction Type shortcuts

This process assumes that there is already one or more Projects in Active.

**To use Issue and Prediction Type shortcuts:**

1. Log in to the Encord platform.
   The landing page for the Encord platform appears.

2. Click **Active** in the main menu.
   The landing page for Active appears.

3. Click the Project.
   The landing page for the Project appears with the *Explorer* tab selected.

4. Click **Data**, **Labels**, or **Predictions**.
   The Explorer workspace changes based on what you clicked. The Overview tab displays with the shortcuts.

5. Click a shortcut.
   A filter is applied to the images. The images appearing in the Explorer workspace changes depending on which shortcut you click.

6. Click **Filter** if you want to modify the filter settings.

7. Further search, sort, and filter the data.

8. Create a Collection based on the results.

9. Create a Dataset (and Project) and send that Dataset to Annotate.

10. Further annotate your data.

11. Rinse and repeat until you have the dataset you need for optimal model performance.


# Data Visualization
Source: https://docs.encord.com/platform-documentation/Validation/active-basics/data-visualization



In the Grid view, each image and frame displays in a card/tile. Within each tile, you can include a variety of information.

**General**

* <b>Title:</b> The file name for the frame.
* <b>Selected metric:</b> The data, label, video, or prediction metric the frame is being sorted by.
* <b>Collections:</b> Then number of Collections the frame belongs to. Mousing over the number displays the Collection names.
* <b>Class:</b> The label/classifications in the frame.
* <b>IOU:</b> The Intersection of Union between the prediction labels and ground truth labels. A value of 1 means there is perfect overlap between the prediction and ground truth labels. A value of 0 means there is no overlap between the prediction and ground truth labels.
* <b>Workflow stage:</b> The Workflow stage where the data unit resides.
* <b>Priority:</b> The priority assigned to the task (data unit) in Annotate.

**Prediction / Labels**

* <b>Show ground truth:</b> Displays ground truth labels on the frame with predictions.
* <b>IOU Threshold:</b> Specifies the value that determines the cutoff between true positive and false positive predictions. Predictions with an IoU greater than or equal to this threshold are considered true positives, while those below it are considered false positives.
* <b>Min Confidence Threshold:</b> Specifies the confidence value to filter your frames with predictions.

## Display information on Grid view

The grid is always visible on the left side of the Data Explorer. You can toggle a right-hand panel — **Embeddings**, **Analytics**, or **Map** — using the toolbar icons or keyboard shortcuts. Only one panel is active at a time; click the active icon again to close the panel.

<Note>
  The Map panel is not available in the Annotation project Explore view. The Analytics panel is not available in the Index (shared folder) context.
</Note>

**Keyboard shortcuts**

| Shortcut  | Action                      |
| --------- | --------------------------- |
| `V` → `G` | Focus the grid              |
| `V` → `E` | Toggle the Embeddings panel |
| `V` → `A` | Toggle the Analytics panel  |
| `V` → `M` | Toggle the Map panel        |

You can also deep-link directly to a panel by appending `?panel=embeddings`, `?panel=analytics`, or `?panel=map` to the URL. Legacy view-specific URLs redirect automatically and preserve your query parameters.

1. Navigate to **Data** > **Explore** and select a folder.

2. Use the toolbar icons to toggle the panel you want to display alongside the grid: **Embeddings**, **Analytics**, or **Map**.

   ![Data Visualization](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-data-visualization.gif)

3. Click **Display** on the far right of the screen.

4. Specify the data required to display on each card/tile under *Card details*.

<Note>
  Not all information is available for viewing under every tab (Video, Data, Labels, Prediction).
</Note>

## Embeddings Panel

When you open the Embeddings panel, the scatter plot appears on the right while the grid remains visible on the left. You can draw a selection box on the scatter plot to immediately filter the grid to matching items — without switching views.

* **Box selection** — draw a rectangle on the scatter plot to filter the grid to the selected items. A filter pill appears in the toolbar; dismiss the pill to clear the selection.
* **NLS / similarity search** — when a similarity search is active, matching points appear in color on the scatter plot and non-matching points appear in gray. This highlighting composes with any active box selection.
* **Adding items to collections** — use the unified selection toolbar at the bottom of the grid to add or remove selected items from collections. The per-view selection toolbar has been removed; the grid toolbar is the single mechanism for all collection actions.

<Note>
  Hovering over a point in the Embeddings scatter plot no longer shows an image preview tooltip. The grid on the left serves this purpose.
</Note>

## Filter Predictions by IOU and Confidence

1. Navigate to **Data** > **Explore** and select a folder.

2. Click **Predictions**.
   ![Predictions](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-data-visualization-predictions.gif)

3. Click **Display** on the far right of the screen.

4. Expand the **Prediction** section.

5. Adjust the **IOU Threshold**.
   Depending on the IOU of the ground truth and prediction labels a TP or FP icon appears on each frame.

6. Adjust the **Min Confidence Threshold**.
   Frames under the threshold are filtered from view.

## Analytics Panel

The Analytics panel opens as a right-hand panel alongside the always-visible grid. Use the `V` → `A` keyboard shortcut or the toolbar icon to toggle it.

* **Apply to grid** — in the Slice Editor, click **Apply to grid** to copy a slice's filters into the shared toolbar filter set. The grid updates immediately without navigating away. This button was previously labeled **View in Explorer**.
* **Correlation chart** — the **View in Explorer** context-menu option on the Correlation chart has been removed. Use **Apply Filter** to apply a filter directly.
* **Current Filters chip** — the **Current Filters** editor chip and its popover in the Analytics slice strip are no longer interactive. The chip remains visible as a read-only indicator of the active filter set.

## Viewer Role Access

Users with the **Viewer** role on Workflow projects can now access the **Explore** tab and browse the Explorer in read-only mode.

<Note>
  The Explore tab remains inaccessible for all roles on ManualQA projects. Team Managers see the Explore tab in the navigation but land on the statistics fallback view — this is pre-existing behavior and is unchanged.
</Note>

Viewers can:

* Browse the grid, analytics, and embeddings views
* Apply existing filters and collections
* Post comments and raise issues

Viewers cannot:

* Create, edit, or delete collections
* Add or remove items from collections (collection tags remain visible in item previews)
* Create, edit, delete, or save filter presets
* Import or delete prediction sets (**Manage** button is hidden)
* Use bulk actions (priority, bulk classify, change class, delete labels, export CSV)

## Item Preview Sidebar

When you open an item's preview sidebar, the **Objects** and **Classifications** panels now display the values entered for text and numeric annotation attributes directly inline — without needing to open the full annotation editor.

* **Text attributes** — free-form text answers (for example, captions or notes) appear beneath their parent object or classification.
* **Numeric attributes** — numeric answers (for example, scores or counts) appear beneath their parent object or classification.
* **Long text values** — values that exceed the available width are truncated with an ellipsis (`…`). Hover over the truncated value to see the full text in a tooltip.
* **Empty attributes** — if no value has been entered for an attribute, the sidebar displays `NA`.

<Note>
  This applies to both the **Objects** and **Classifications** panels in the sidebar. Radio button and checklist attribute selections continue to display as expandable child nodes, as before.
</Note>


# Compare Model Performance
Source: https://docs.encord.com/platform-documentation/Validation/active-how-to/active-compare-model-performance



You have trained your model, and now you are ready to see how it performs.  It is time to perform a cycle of the Active model optimization workflow.

![Encord Active workflow](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-workflow-model-optimization.png)

Now you want to compare your model's performance before using Encord (or maybe after running a number of data curation and label validation cycles). Active supports doing direct model prediction performance comparison from within your Active Project.

<AccordionGroup>
  <Accordion title="To compare your model's performance:">
    This process assumes you have already imported your model's predictions in to Active at least twice.

    1. Navigate to **Projects**

    2. Open the **Explore** tab.

    3. Click **Model Evaluation**.
       The *Model Evaluation* page appears with *Summary* displaying.

    4. Select an entry from the dropdown under **Prediction Set** under *Overview*.

    5. Select an entry from the dropdown under **Compare against** under *Overview*.

    6. Click through the various entries on the left side of the Model Evaluation page to view the comparison.

    7. Add more data and start the data curation, label validation, and model optimization cycles until the model reaches a performance level that you require.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="To compare your model's performance from scratch:">
    This process assumes you are just getting started with Encord. You have not trained your model yet. You are using Encord to prepare your data for annotation, annotating your data, labeling your data, validating your labels, fixing any label issues, then training your model.

    1. Navigate to **Projects**

    2. Open the **Explore** tab.

    3. Click **Model Evaluation**.
       The *Model Evaluation* page appears with *Summary* displaying.

    4. [Import a Prediction Set](/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud).

    5. \[Perform data curation on your Project in Active]\(/platform-documentation/Validation/validation-tutorials/validation-
       use-cases#data-cleansingcuration).

    6. Label and review your data in Annotate.

    7. Sync the Active Project with the updated Annotate Project.

    8. Perform label validation on your updated and synced Project.

    9. Send the Project to Annotate.

    10. Label and review your data in Annotate.

    11. Retrain your model using the curated and validated data/labels.

    12. Click the Active Project.
        The Project opens on the *Explorer*.

    13. Click **Model Evaluation**.
        The *Model Evaluation* page appears.

    14. [Import the updated Prediction Set](/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud).

    15. Select an entry from the dropdown under **Prediction Set** under *Overview*.

    16. Select an entry from the dropdown under **Compare against** under *Overview*.

    17. Click through the various entries on the left side of the Model Evaluation page to view the comparison.

    18. Add more data and start the data curation, label validation, and model optimization cycles until the model reaches a performance level that you require.
  </Accordion>
</AccordionGroup>


# Import Predictions
Source: https://docs.encord.com/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud



<Tip>Do you already know what you are doing and only want to look over a Jupyter Notebook example to import your predictions? We provide one [here](#end-to-end-prediction-import-example).</Tip>

<div>
  <iframe />
</div>

To upload predictions in Encord, you need to create a prediction branch. This guide explains everything you need to know for importing predictions.

### Predictions Workflow

1. **Import Predictions to Project:** Start by importing your labels and predictions into your Project.
2. **Analyze the Predictions:** Once your predictions are imported, specify the prediction set you want to analyze.
3. **Select the Predictions:** Once analysis completes, select the prediction set you want to view in the **Explore** tab of your Project.

## Supported Prediction Formats

**[Encord Format (Recommended)](/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud#import-encord-format-predictions)**

* Supports multi-level nested classifications (radio, checklist, or free-form text) under objects or classifications.
* Handles all object types and classification.

<Note>
  - Only top-level objects and classifications are considered when calculating in model metrics.
</Note>

**[COCO Format](/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud#import-coco-labels-as-predictions)**

* Does not support multiple levels of nested classifications (radio, checklist, or free-form text) under tools or classifications.

### Confidence Score

You can include confidence scores when uploading predictions. Encord automatically calculates model metrics based on your prediction set and assigned confidence scores.

## Prediction Branches

When importing prediction sets into Encord, they are added as branches to individual label rows on your data units (images, videos, audio). Each data unit has the following:

* A MAIN branch for ground truth annotations or pre-labels.
* Optional Consensus branches and Prediction branches for different prediction sets.

![Label branches](https://storage.googleapis.com/docs-media.encord.com/static/img/active/prediction-branch.png)

<Tip>You can [export main branch labels from the UI](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels). [Consensus labels and model predictions can only be exported using the SDK](/sdk-documentation/sdk-labels/sdk-export#export-all-consensus-labels).</Tip>

## List Branches

Use `list_branches` to list all the branches (imported or Consensus) in a Project.

```python theme={"dark"}
# Import dependencies
from encord import EncordUserClient

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 Project ID

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",
)

project = user_client.get_project(PROJECT_ID)
with open("branches.txt", "w") as output_file:
    for branch_name in project.list_branches():
        output_file.write(f"{branch_name}\n")
```

## 1. Import Predictions

Import your predictions to a Project. Encord currently supports importing predictions from the Encord format and from COCO.

### Import Encord-Format Predictions

Use `branch_name` to create a prediction branch in `label_rows_v2` for a data unit.

<Warning>
  * `branch_name` supports alphanumeric characters (a-z, A-Z, 0-9) and is case sensitive
  * `branch_name` supports the following special characters: hyphens (-), underscores (\_), and periods (.)
</Warning>

<AccordionGroup>
  <Accordion title="Bounding Box">
    **Example 1**

    Imports a single bounding box (`Cherry`) to a single image (`cherry_001.png`).

    **Example 2:**

    Imports three instances (tracking an object across three sequential frames: 103, 104, and 105) of a bounding box (`Cherry`) to a video (`Cherries_video.mp4`).

    **Example 3**

    Imports three bounding boxes (`Cherry`) to a single image (`cherry_001.png`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 103, 104, 105, object 2 - frames 206, 207, 208, and object 3 - frames 313, 315, 317) of three bounding boxes (`Cherry`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Bounding Box Template theme={"dark"}
      # 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

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"
      PROJECT_HASH = "<unique-id-of-your-project>"
      PREDICTION_BRANCH_NAME = "<name-of-your-prediction-branch>"
      ONTOLOGY_OBJECT_TITLE = "<name-of-ontology-object>" # Name of object label in your Ontology
      DATA_UNIT_TITLES = ["<data-unit-title-1>", "<data-unit-title-2>"]  # List of specific data units

      # Ensure SSH path and project hash are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_HASH, "Project hash cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the prediction branch
      project = user_client.get_project(PROJECT_HASH)
      all_prediction_branch_rows = project.list_label_rows_v2(branch_name=PREDICTION_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      prediction_branch_rows = [
          row for row in all_prediction_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not prediction_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in prediction_branch_rows])

      # Retrieve the specified ontology object by title
      ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      # Initialize labels for each selected label row in the prediction branch
      with project.create_bundle() as bundle:
          for row in prediction_branch_rows:
              row.initialise_labels(bundle=bundle)

      # Add bounding box predictions to each filtered label row
      for row in prediction_branch_rows:
          # Instantiate an object instance for bounding box predictions
          inst = ontology_object.create_instance()
          inst.set_for_frames(
              coordinates=BoundingBoxCoordinates(
                  height=0.1,
                  width=0.1,
                  top_left_x=0.5,
                  top_left_y=0.5,
              ),
              frames=0,  # Apply to the specified frame
              manual_annotation=False,  # Set to False as this is a prediction
              confidence=1, # Confidence of your prediction
          )

          # Add the prediction instance to the label row
          row.add_object_instance(inst)

      with project.create_bundle() as bundle:
          # Save the row with predictions within the bundle
          for row in prediction_branch_rows:
              row.save(bundle=bundle)
      ```

      ```python Example 1 theme={"dark"}
      # 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

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "80ae53e3-594c-4120-a108-ee4af105bff3"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"
      ONTOLOGY_OBJECT_TITLE = "Cherry" # Name of object label in your Ontology
      DATA_UNIT_TITLES = ["cherry_001.png"]  # List of specific data units

      # Ensure SSH path and project hash are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_HASH, "Project hash cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the prediction branch
      project = user_client.get_project(PROJECT_HASH)
      all_prediction_branch_rows = project.list_label_rows_v2(branch_name=PREDICTION_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      prediction_branch_rows = [
          row for row in all_prediction_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not prediction_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in prediction_branch_rows])

      # Retrieve the specified ontology object by title
      ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      # Initialize labels for each selected label row in the prediction branch
      with project.create_bundle() as bundle:
          for row in prediction_branch_rows:
              row.initialise_labels(bundle=bundle)

      # Add bounding box predictions to each filtered label row
      for row in prediction_branch_rows:
          # Instantiate an object instance for bounding box predictions
          inst = ontology_object.create_instance()
          inst.set_for_frames(
              coordinates=BoundingBoxCoordinates(
                  height=0.1,
                  width=0.1,
                  top_left_x=0.5,
                  top_left_y=0.5,
              ),
              frames=0,  # Apply to the specified frame
              manual_annotation=False,  # Set to False as this is a prediction
              confidence=1, # Confidence of your prediction
          )

          # Add the prediction instance to the label row
          row.add_object_instance(inst)

      with project.create_bundle() as bundle:
          for row in prediction_branch_rows:
              # Save the row with predictions within the bundle
              row.save(bundle=bundle)
      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"
      ONTOLOGY_OBJECT_TITLE = "Cherry"
      DATA_UNIT_TITLES = ["Cherries_video.mp4"]  # List of specific video data units

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the prediction branch
      project = user_client.get_project(PROJECT_HASH)
      all_prediction_branch_rows = project.list_label_rows_v2(branch_name=PREDICTION_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      prediction_branch_rows = [
          row for row in all_prediction_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not prediction_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in prediction_branch_rows])

      # Retrieve the specified ontology object by title
      box_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      with project.create_bundle() as bundle:
          # Initialize labels for each selected label row in the prediction branch
          for label_row in prediction_branch_rows:
              label_row.initialise_labels(bundle=bundle)

      # Define frame coordinates for video tracking
      coordinates_per_frame = {
          103: BoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
          ),
          104: BoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
          ),
          105: BoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
          ),
      }

      # Add bounding box predictions to each filtered label row across specified frames
      for label_row in prediction_branch_rows:
          # Instantiate an object instance for bounding box predictions
          box_object_instance = box_ontology_object.create_instance()
          
          # Apply bounding box coordinates for each specified frame
          for frame_number, coordinates in coordinates_per_frame.items():
              box_object_instance.set_for_frames(
                  coordinates=coordinates, 
                  frames=frame_number,  # Specify the frame number
                  manual_annotation=False  # Mark as a prediction
              )
          
          # Add the object instance to the label row
          label_row.add_object_instance(box_object_instance)
          
      with project.create_bundle() as bundle:
          for label_row in prediction_branch_rows:
              # Save the label row with the updated predictions within the bundle
              label_row.save(bundle=bundle)
      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-II"
      ONTOLOGY_OBJECT_TITLE = "Cherry"
      DATA_UNIT_TITLES = ["cherry_001.png"]  # List of specific image data units

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the prediction branch
      project = user_client.get_project(PROJECT_HASH)
      all_prediction_branch_rows = project.list_label_rows_v2(branch_name=PREDICTION_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      prediction_branch_rows = [
          row for row in all_prediction_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not prediction_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in prediction_branch_rows])

      # Retrieve the specified ontology object by title
      box_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      with project.create_bundle() as bundle:
          # Initialize labels for each selected label row in the prediction branch
          for label_row in prediction_branch_rows:
              label_row.initialise_labels(bundle=bundle)

      # Add bounding box predictions to each filtered label row
      for label_row in prediction_branch_rows:
          # Define bounding box coordinates for each prediction
          bounding_boxes = [
              BoundingBoxCoordinates(height=0.1, width=0.1, top_left_x=0.2, top_left_y=0.2),
              BoundingBoxCoordinates(height=0.1, width=0.1, top_left_x=0.3, top_left_y=0.3),
              BoundingBoxCoordinates(height=0.1, width=0.1, top_left_x=0.4, top_left_y=0.4),
          ]

          # Instantiate and set predictions for each bounding box
          for coordinates in bounding_boxes:
              box_object_instance = box_ontology_object.create_instance()
              box_object_instance.set_for_frames(
                  coordinates=coordinates,
                  frames=0,  # Image frame
                  manual_annotation=False,  # Mark as prediction
                  confidence=1.0,
              )

              # Add each object instance to the label row
              label_row.add_object_instance(box_object_instance)
          
      with project.create_bundle() as bundle:
          for label_row in prediction_branch_rows:
              # Save the label row with the updated predictions within the bundle
              label_row.save(bundle=bundle)
      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-II"
      ONTOLOGY_OBJECT_TITLE = "Cherry"
      DATA_UNIT_TITLES = ["Cherries_video.mp4"]  # List of specific video data units

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the prediction branch
      project = user_client.get_project(PROJECT_HASH)
      all_prediction_branch_rows = project.list_label_rows_v2(branch_name=PREDICTION_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      prediction_branch_rows = [
          row for row in all_prediction_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not prediction_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in prediction_branch_rows])

      # Retrieve the specified ontology object by title
      box_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      with project.create_bundle() as bundle:
          # Initialize labels for each selected label row in the prediction branch
          for label_row in prediction_branch_rows:
              label_row.initialise_labels(bundle=bundle)

      # Define frame coordinates for tracking across multiple frames for each object
      tracking_coordinates = [
          {  # First object tracked across frames 103, 104, 105
              103: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.2, top_left_y=0.2),
              104: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.3, top_left_y=0.3),
              105: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.4, top_left_y=0.4)
          },
          {  # Second object tracked across frames 206, 207, 208
              206: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.2, top_left_y=0.2),
              207: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.3, top_left_y=0.3),
              208: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.4, top_left_y=0.4)
          },
          {  # Third object tracked across frames 313, 315, 317
              313: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.2, top_left_y=0.2),
              315: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.3, top_left_y=0.3),
              317: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.4, top_left_y=0.4)
          },
      ]

      # Add bounding box predictions to each filtered label row across specified frames
      for label_row in prediction_branch_rows:
          for frame_coordinates in tracking_coordinates:
              box_object_instance = box_ontology_object.create_instance()
              
              for frame_number, coordinates in frame_coordinates.items():
                  box_object_instance.set_for_frames(
                      coordinates=coordinates, 
                      frames=frame_number,
                      manual_annotation=False,  # Mark as a prediction
                      confidence=1.0
                  )
              
              # Add each object instance to the label row
              label_row.add_object_instance(box_object_instance)
          
      with project.create_bundle() as bundle:
          for label_row in prediction_branch_rows:
              # Save the label row with the updated predictions within the bundle
              label_row.save(bundle=bundle)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Rotatable Bounding Box">
    **Example 1**

    Imports a single rotatable bounding box (`Other type of fruit`) to a single image (`apple_001.png`).

    **Example 2**

    Imports three instances (tracking an object across three sequential frames: 120, 121, and 122) of a bounding box (`Other type of fruit`) to a video (`Cherries_video.mp4`).

    **Example 3**

    Imports three rotatable bounding boxes (`Other type of fruit`) to a single image (`apple_001.png`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 120, 121, 122, object 2 - frames 222, 224, 226, and object 3 - frames 321, 323, 325) of three rotatable bounding boxes (`Other type of fruit`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Import Rotatable Bounding Box Template theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"
      PROJECT_HASH = "<unique-hash-for-project>"
      PREDICTION_BRANCH_NAME = "<name-of-your-prediction-branch>"
      ONTOLOGY_OBJECT_TITLE = "<rotatable-bounding-box-class-title>"
      DATA_UNIT_TITLES = ["<data-unit-title-1>", "<data-unit-title-2>"]  # Specify the data unit titles here

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the prediction branch
      project = user_client.get_project(PROJECT_HASH)
      all_prediction_branch_rows = project.list_label_rows_v2(branch_name=PREDICTION_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      prediction_branch_rows = [
          row for row in all_prediction_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not prediction_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in prediction_branch_rows])

      # Retrieve the specified ontology object by title
      rbb_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      with project.create_bundle() as bundle:
          # Initialize labels for each selected label row in the prediction branch
          for label_row in prediction_branch_rows:
              label_row.initialise_labels(bundle=bundle)

      # Define rotatable bounding box coordinates and frame for each object
      rotatable_bounding_box_predictions = [
          {
              "frame_number": 0,
              "coordinates": RotatableBoundingBoxCoordinates(
                  height=0.3,
                  width=0.2,
                  top_left_x=0.1,
                  top_left_y=0.1,
                  theta=15  # Angle of rotation in degrees
              ),
          },
          {
              "frame_number": 5,
              "coordinates": RotatableBoundingBoxCoordinates(
                  height=0.25,
                  width=0.25,
                  top_left_x=0.15,
                  top_left_y=0.15,
                  theta=30
              ),
          },
          {
              "frame_number": 10,
              "coordinates": RotatableBoundingBoxCoordinates(
                  height=0.2,
                  width=0.3,
                  top_left_x=0.2,
                  top_left_y=0.2,
                  theta=45
              ),
          },
      ]

      # Add rotatable bounding box predictions to each filtered label row
      for label_row in prediction_branch_rows:
          for prediction in rotatable_bounding_box_predictions:
              rbb_object_instance = rbb_ontology_object.create_instance()
              
              rbb_object_instance.set_for_frames(
                  coordinates=prediction["coordinates"],
                  frames=prediction["frame_number"],
                  manual_annotation=False,  # Mark as a prediction
                  confidence=1.0
              )
              
              # Link the object instance to the label row
              label_row.add_object_instance(rbb_object_instance)
          
      with project.create_bundle() as bundle:
          for label_row in prediction_branch_rows:
              # Save the label row with the updated predictions within the bundle
              label_row.save(bundle=bundle)
      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"
      DATA_UNIT_TITLE = "apple_001.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Other type of fruit"  # Ontology class title for rotatable bounding box

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the prediction branch
      project = user_client.get_project(PROJECT_HASH)
      prediction_branch_rows = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,
          data_title_eq=DATA_UNIT_TITLE
      )

      if not prediction_branch_rows:
          print("No matching data unit found in the specified branch.")
      else:
          print("Data unit found:", prediction_branch_rows[0].data_title)

      # Retrieve the specified ontology object by title
      rbb_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      # Prepare for prediction imports by creating a bundle
      with project.create_bundle() as bundle:
          # Initialize labels for the label row in the prediction branch
          label_row = prediction_branch_rows[0]
          label_row.initialise_labels(bundle=bundle)

      # Define the rotatable bounding box coordinates for prediction
      rbb_coordinates = RotatableBoundingBoxCoordinates(
          height=0.23,
          width=0.13,
          top_left_x=0.3,
          top_left_y=0.5,
          theta=95  # Angle of rotation in degrees
      )

      # Add rotatable bounding box prediction to the label row
      rbb_object_instance = rbb_ontology_object.create_instance()
      rbb_object_instance.set_for_frames(
          coordinates=rbb_coordinates,
          frames=0,  # Frame for the image
          manual_annotation=False,  # Mark as a prediction
          confidence=1.0
      )

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

      with project.create_bundle() as bundle:
          # Save the label row with the updated predictions within the bundle
          # (useful if you're calling `initialise_labels` on many label rows
          label_row.save(bundle=bundle)
      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify the prediction branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # The title of the video data unit
      ONTOLOGY_OBJECT_TITLE = "Other type of fruit"  # The ontology object title for the bounding box

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

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

      # Creating multiple instances of a rotatable bounding box - START
      label_row = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Use the prediction branch
          data_title_eq=DATA_UNIT_TITLE
      )[0]


      with project.create_bundle() as bundle:
          # Initialize labels for the selected label row in the prediction branch
          label_row.initialise_labels(bundle=bundle)

      # Find a rotatable bounding box annotation object in the project ontology
      rbb_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Define the coordinates for the rotatable bounding boxes across frames
      coordinates_per_frame = {
          120: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
              theta=23
          ),
          121: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
              theta=27
          ),
          122: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
              theta=57
          ),
      }

      # Iterate through the frames and create instances for each bounding box
      for frame_number, coordinates in coordinates_per_frame.items():
          # Instantiate an object instance from the ontology node for each frame
          rbb_object_instance: ObjectInstance = rbb_ontology_object.create_instance()

          # Set the coordinates for the rotatable bounding box for this frame
          rbb_object_instance.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=False,  # Mark as a prediction
              confidence=1.0  # Optional confidence score
          )

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

      with project.create_bundle() as bundle:
          # Save the label row with the updated predictions within the bundle
          label_row.save(bundle=bundle)
      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-II"  # Specify the prediction branch
      DATA_UNIT_TITLE = "apple_001.jpg"  # The title of the image data unit
      ONTOLOGY_OBJECT_TITLE = "Other type of fruit"  # The ontology object title for the bounding box

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

      # Get the project and list label rows for the prediction branch
      project: Project = user_client.get_project(PROJECT_HASH)
      label_row = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Use the prediction branch
          data_title_eq=DATA_UNIT_TITLE
      )[0]

      with project.create_bundle() as bundle:
          # Initialize labels for the selected label row in the prediction branch
          label_row.initialise_labels(bundle=bundle)

      # Find the rotatable bounding box annotation object in the project ontology
      rbb_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Define rotatable bounding box instances with different coordinates
      rotatable_bounding_boxes = [
          RotatableBoundingBoxCoordinates(
              height=0.23,
              width=0.13,
              top_left_x=0.1,
              top_left_y=0.2,
              theta=37
          ),
          RotatableBoundingBoxCoordinates(
              height=0.23,
              width=0.13,
              top_left_x=0.3,
              top_left_y=0.5,
              theta=95
          ),
          RotatableBoundingBoxCoordinates(
              height=0.23,
              width=0.13,
              top_left_x=0.4,
              top_left_y=0.6,
              theta=70
          ),
      ]

      # Iterate over each bounding box and apply them as predictions to the label row
      for rbb_coordinates in rotatable_bounding_boxes:
          rbb_object_instance: ObjectInstance = rbb_ontology_object.create_instance()

          rbb_object_instance.set_for_frames(
              coordinates=rbb_coordinates,
              frames=0,  # Image frame
              manual_annotation=False,  # Mark as a prediction
              confidence=1.0
          )

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

      with project.create_bundle() as bundle:
          # Save the label row with the updated predictions within the bundle
          label_row.save(bundle=bundle)
      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "<name-of-your-prediction-branch>"  # Specify the prediction branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # The title of the video data unit
      ONTOLOGY_OBJECT_TITLE = "Other type of fruit"  # The ontology object title for the bounding box

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

      # Get the project and list label rows for the prediction branch
      project: Project = user_client.get_project(PROJECT_HASH)
      label_row = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Use the prediction branch
          data_title_eq=DATA_UNIT_TITLE
      )[0]

      with project.create_bundle() as bundle:
          # Initialize labels for the selected label row in the prediction branch
          label_row.initialise_labels(bundle=bundle)

      # Find the rotatable bounding box annotation object in the project ontology
      rbb_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Define frame coordinates for the first rotatable bounding box
      coordinates_per_frame_01 = {
          120: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
              theta=23
          ),
          121: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
              theta=27
          ),
          122: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
              theta=57
          ),
      }

      # Create and link the first rotatable bounding box to the label row
      rbb_object_instance_01: ObjectInstance = rbb_ontology_object.create_instance()
      for frame_number, coordinates in coordinates_per_frame_01.items():
          rbb_object_instance_01.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=False,  # Mark as a prediction
              confidence=1.0  # Optional confidence score
          )
      label_row.add_object_instance(rbb_object_instance_01)

      # Define frame coordinates for the second rotatable bounding box
      coordinates_per_frame_02 = {
          222: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
              theta=23
          ),
          224: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
              theta=27
          ),
          226: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
              theta=57
          ),
      }

      # Create and link the second rotatable bounding box to the label row
      rbb_object_instance_02: ObjectInstance = rbb_ontology_object.create_instance()
      for frame_number, coordinates in coordinates_per_frame_02.items():
          rbb_object_instance_02.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=False,  # Mark as a prediction
              confidence=1.0  # Optional confidence score
          )
      label_row.add_object_instance(rbb_object_instance_02)

      # Define frame coordinates for the third rotatable bounding box
      coordinates_per_frame_03 = {
          321: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
              theta=23
          ),
          323: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
              theta=27
          ),
          325: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
              theta=57
          ),
      }

      # Create and link the third rotatable bounding box to the label row
      rbb_object_instance_03: ObjectInstance = rbb_ontology_object.create_instance()
      for frame_number, coordinates in coordinates_per_frame_03.items():
          rbb_object_instance_03.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=False,  # Mark as a prediction
              confidence=1.0  # Optional confidence score
          )
      label_row.add_object_instance(rbb_object_instance_03)

      with project.create_bundle() as bundle:
          # Save the label row with the updated predictions within the bundle
          label_row.save(bundle=bundle)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Polygons">
    **Example 1**

    Imports a single polygon (`Persimmon`) to a single image (`persimmon_001.jpg`).

    **Example 2**

    Imports three instances (tracking an object across three sequential frames: 143, 144, and 145) of a polygon (`Persimmon`) to a video (`Cherries_video.mp4`).

    **Example 3**

    Imports three polygons (`Persimmon`) to a single image (`persimmon_001.jpg`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 153, 154, 155, object 2 - frames 242, 244, 246, and object 3 - frames 343, 345, 347) of three polygons (`Persimmon`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Import Polygon Template theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"
      PROJECT_HASH = "<unique-project-hash>"
      PREDICTION_BRANCH_NAME = "<name-of-your-prediction-branch>"  # Specify the prediction branch
      DATA_UNIT_TITLE = "<name-of-data-unit>"  # The title of the data unit (image or video)
      ONTOLOGY_OBJECT_TITLE = "<object-name>"  # The ontology object title for the polygon

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

      # Get the project and list label rows for the prediction branch
      project: Project = user_client.get_project(PROJECT_HASH)
      prediction_branch_rows = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Use the prediction branch
          data_title_eq=DATA_UNIT_TITLE
      )

      if not prediction_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in prediction_branch_rows])

      # Initialize labels for each selected label row in the prediction branch
      label_row = prediction_branch_rows[0]
      label_row.initialise_labels()

      # Find a polygon annotation object in the project ontology
      polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the polygon ontology node
      polygon_object_instance: ObjectInstance = polygon_ontology_object.create_instance()

      # Define the polygon coordinates
      polygon_coordinates = PolygonCoordinates([
          PointCoordinate(0.1, 0.2),
          PointCoordinate(0.3, 0.4),
          PointCoordinate(0.5, 0.6),
          PointCoordinate(0.7, 0.8)
      ])

      # Set the polygon prediction for the specified frame
      polygon_object_instance.set_for_frames(
          coordinates=polygon_coordinates,
          frames=0,  # Specify the frame number
          manual_annotation=False,  # Mark as a prediction
          confidence=1.0  # Optional confidence score
      )

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

      # Save the label row 
      label_row.save()
      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology
      DATA_UNIT_TITLE = "persimmon_001.jpg"  # Specific data unit title

      # Ensure SSH path and project hash are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_HASH, "Project hash cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      # Get project and list label rows for the specified branch and data unit
      project = user_client.get_project(PROJECT_HASH)
      all_label_rows = project.list_label_rows_v2(branch_name=PREDICTION_BRANCH_NAME)

      # Filter label rows based on the specified data unit title
      label_rows = [
          row for row in all_label_rows 
          if row.data_title == DATA_UNIT_TITLE
      ]

      if not label_rows:
          print(f"No matching label rows found for {DATA_UNIT_TITLE} in branch '{PREDICTION_BRANCH_NAME}'.")
          exit()  # Nothing to do so exit early

      print("Label rows found:", [row.data_title for row in label_rows])

      with project.create_bundle() as bundle:
          # Prepare for labeling
          for label_row in label_rows:
              label_row.initialise_labels(bundle=bundle)

      for label_row in label_rows:
          # Retrieve the specified ontology object by title
          polygon_ontology_object = project.ontology_structure.get_child_by_title(
              title=ONTOLOGY_OBJECT_TITLE,
              type_=Object
          )

          # Instantiate an object instance from the polygon ontology node
          polygon_object_instance = polygon_ontology_object.create_instance()

          # The x,y coordinates of each polygon vertex
          polygon_object_instance.set_for_frames(
              coordinates=PolygonCoordinates(
                  [PointCoordinate(.1, .1), PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4)]
              ),
              frames=0,  # Apply to the specified frame
              manual_annotation=True,  # Set to True for manual annotation
              confidence=1.0,  # Confidence of your prediction
          )

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


      with project.create_bundle() as bundle:
          for label_row in label_rows:
              # Save the label row with the polygon object instance within the bundle
              label_row.save(bundle=bundle)

      print("Label rows updated with polygon instances.")
      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

      # Ensure SSH path and project hash are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_HASH, "Project hash cannot be None"

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

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

      # Retrieve the label row for the specified data unit
      label_row = project.list_label_rows_v2(
          data_title_eq=DATA_UNIT_TITLE
      )[0]

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

      # Find the polygon annotation object in the project ontology
      polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Coordinates for each frame
      coordinates_per_frame = {
          143: PolygonCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
          144: PolygonCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
          145: PolygonCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
      }

      # Create and link polygon object instances for each frame
      for frame_number, coordinates in coordinates_per_frame.items():
          polygon_object_instance: ObjectInstance = polygon_ontology_object.create_instance()
          polygon_object_instance.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=True,  # Set to True for manual annotation
              confidence=1.0,  # Set confidence level as needed
          )
          
          # Link the object instance to the label row
          label_row.add_object_instance(polygon_object_instance)

      # Save the label row 
      label_row.save()
      print("Label row updated with polygon instances.")

      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "persimmon_001.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

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

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

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

      label_row.initialise_labels()

      # Find a polygon annotation object in the project ontology
      polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Function to create a polygon object instance
      def create_polygon_instance(ontology_object, coordinates, frame, manual_annotation=True, confidence=1.0):
          polygon_instance = ontology_object.create_instance()
          polygon_instance.set_for_frames(
              coordinates=coordinates,
              frames=frame,
              manual_annotation=manual_annotation,
              confidence=confidence,
          )
          return polygon_instance

      # Define coordinates for polygons
      polygon_coordinates = [
          PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4)]),
          PolygonCoordinates([PointCoordinate(.15, .15), PointCoordinate(.25, .25), PointCoordinate(.35, .35), PointCoordinate(.15, .45)]),
          PolygonCoordinates([PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4), PointCoordinate(.2, .5)]),
      ]

      # Create and link polygon instances for each set of coordinates
      for coords in polygon_coordinates:
          polygon_instance = create_polygon_instance(polygon_ontology_object, coords, frame=0)
          label_row.add_object_instance(polygon_instance)

      # Save the label row with polygon instances
      label_row.save()
      print("Label row updated with polygon instances.")

      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

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

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

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

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

      # Find a polygon annotation object in the project ontology
      polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Function to create and add a polygon instance
      def add_polygon_instance(label_row, ontology_object, coordinates_per_frame):
          polygon_instance = ontology_object.create_instance()

          for frame_number, coordinates in coordinates_per_frame.items():
              polygon_instance.set_for_frames(
                  coordinates=coordinates,
                  frames=frame_number,
                  manual_annotation=True,  # Set to True for manual annotation
                  confidence=1.0,  # Set confidence level as needed
              )
          
          # Link the object instance to the label row
          label_row.add_object_instance(polygon_instance)

      # Coordinates for each polygon
      coordinates_list = [
          {
              153: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              154: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              155: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
          },
          {
              242: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              244: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              246: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
          },
          {
              343: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              345: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              347: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
          },
      ]

      # Add polygon instances
      for coordinates in coordinates_list:
          add_polygon_instance(label_row, polygon_ontology_object, coordinates)

      # Save the label row with polygon instances
      label_row.save()
      print("Label row updated with polygon instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Polyline">
    **Example 1**

    Imports a single polyline (`Branch`) to a single image (`persimmon_001.jpg`).

    **Example 2**

    Imports three instances (tracking an object across three sequential frames: 146, 147, and 148) of a polygon (`Branch`) to a video (`Cherries_video.mp4`).

    **Example 3**

    Imports three polylines (`Branch`) to a single image (`persimmon_001.jpg`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 246, 247, 248, object 2 - frames 346, 347, 348, and object 3 - frames 446, 447, 448) of three polylines (`Branch`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Import Polyline Template theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_HASH = "<unique-project-hash>"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction branch
      DATA_UNIT_TITLE = "<name-of-data-unit>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<object-name>"  # Name of the polyline object in your ontology

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

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

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

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

      # Find a polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.x1, .y1), PointCoordinate(.x1, .y1), PointCoordinate(.x3, .y3), PointCoordinate(.13, .456)]
          ),
          # Add the polyline to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the polyline instance
      label_row.save()
      print("Label row updated with polyline instance.")

      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "apple_001.png"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Branch"  # Name of the polyline object in your ontology

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

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

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

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

      # Find a polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4)]
          ),
          # Add the polyline to the image
          frames=0,  # Specify the frame number
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the polyline instance 
      label_row.save()
      print("Label row updated with polyline instance.")

      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Branch"  # Name of the polyline object in your ontology

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

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

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

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

      # Find a polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()

      # Coordinates for each frame
      coordinates_per_frame = {
          146: PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]
          ),
          147: PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]
          ),
          148: PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]
          ),
      }

      # Set coordinates for each frame in the polyline object instance
      for frame_number, coordinates in coordinates_per_frame.items():
          polyline_object_instance.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True
          )

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

      # Save the label row with the polyline instance
      label_row.save()
      print("Label row updated with polyline instance.")

      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "apple_001.png"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Branch"  # Name of the polyline object in your ontology

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

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

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

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

      # Find a polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Polyline 1 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance01: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance01.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4)]
          ),
          # Add the polyline to the image
          frames=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance01)
      # Polyline 1 - END

      # Polyline 2 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance02: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance02.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.15, .15), PointCoordinate(.25, .25), PointCoordinate(.35, .35), PointCoordinate(.45, .45)]
          ),
          # Add the polyline to the image
          frames=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance02)
      # Polyline 2 - END

      # Polyline 3 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance03: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance03.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.17, .17), PointCoordinate(.27, .27), PointCoordinate(.37, .37), PointCoordinate(.47, .47)]
          ),
          # Add the polyline to the image
          frames=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance03)
      # Polyline 3 - END

      # Save the label row with the polyline instances
      label_row.save()
      print("Label row updated with polyline instances.")
      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Branch"  # Name of the polyline object in your ontology

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

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

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

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

      # Find a polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Polyline 1 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance01: ObjectInstance = polyline_ontology_object.create_instance()

      coordinates_per_frame = {
          246: PolylineCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
          247: PolylineCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
          248: PolylineCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          polyline_object_instance01.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True
          )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance01)
      # Polyline 1 - END

      # Polyline 2 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance02: ObjectInstance = polyline_ontology_object.create_instance()

      coordinates_per_frame = {
          346: PolylineCoordinates(
              [PointCoordinate(.11, .11),
               PointCoordinate(.21, .11),
               PointCoordinate(.31, .21),
               PointCoordinate(.11, .31)]
          ),
          347: PolylineCoordinates(
              [PointCoordinate(.11, .11),
               PointCoordinate(.21, .11),
               PointCoordinate(.31, .21),
               PointCoordinate(.11, .31)]
          ),
          348: PolylineCoordinates(
              [PointCoordinate(.11, .11),
               PointCoordinate(.21, .11),
               PointCoordinate(.31, .21),
               PointCoordinate(.11, .31)]
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          polyline_object_instance02.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True
          )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance02)
      # Polyline 2 - END

      # Polyline 3 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance03: ObjectInstance = polyline_ontology_object.create_instance()

      coordinates_per_frame = {
          446: PolylineCoordinates(
              [PointCoordinate(.21, .21),
               PointCoordinate(.22, .21),
               PointCoordinate(.23, .22),
               PointCoordinate(.21, .23)]
          ),
          447: PolylineCoordinates(
              [PointCoordinate(.21, .21),
               PointCoordinate(.22, .21),
               PointCoordinate(.23, .22),
               PointCoordinate(.21, .23)]
          ),
          448: PolylineCoordinates(
              [PointCoordinate(.21, .21),
               PointCoordinate(.22, .21),
               PointCoordinate(.23, .22),
               PointCoordinate(.21, .23)]
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          polyline_object_instance03.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True
          )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance03)
      # Polyline 3 - END

      # Save the label row with the polyline instances
      label_row.save()
      print("Label row updated with polyline instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Keypoint">
    **Example 1**

    Imports a single keypoint (`Pedicel`) to a single image (`blueberry_003.png`).

    **Example 2**

    Imports three instances (tracking an object across three sequential frames: 143, 144, and 145) of a keypoint (`Pedicel`) to a video (`Blueberries_video.mp4`).

    **Example 3**

    Imports three keypoints (`Pedicel`) to a single image (`blueberry_003.png`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 143, 144, 145, object 2 - frames 242, 244, 246, and object 3 - frames 343, 345, 347) of three keypoints (`Pedicel`) to a video (`Blueberries_video.mp4`).

    <CodeGroup>
      ```python Import Keypoint Template theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_HASH = "<unique-project-hash>"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction branch
      DATA_UNIT_TITLE = "<name-of-data-unit>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<object-name>"  # Name of the keypoint object in your ontology

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

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

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

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

      # Find a keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()

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

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

      # Save the label row with the keypoint instance
      label_row.save()
      print("Label row updated with keypoint instance.")

      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "blueberry_003.png"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Pedicel"  # Name of the keypoint object in your ontology

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

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

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

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

      # Find a keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()

      # The x,y coordinates of the keypoint are specified as follows
      keypoint_object_instance.set_for_frames(
          coordinates=PointCoordinate(
              x=.1,
              y=.1
          ),
          # Add the keypoint to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the keypoint instance
      label_row.save()
      print("Label row updated with keypoint instance.")

      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Pedicel"  # Name of the keypoint object in your ontology

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

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

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

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

      # Find a keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()

      # Define coordinates for keypoints across frames
      coordinates_per_frame = {
          143: PointCoordinate(
              x=.1,
              y=.2
          ),
          144: PointCoordinate(
              x=.11,
              y=.22
          ),
          145: PointCoordinate(
              x=.12,
              y=.23
          ),
      }

      # Set keypoint coordinates for each frame
      for frame_number, coordinates in coordinates_per_frame.items():
          keypoint_object_instance.set_for_frames(
              coordinates=coordinates, 
              frames=frame_number, 
              manual_annotation=True,
              confidence=1.0  # Set confidence level as needed
          )

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

      # Save the label row with the keypoint instance
      label_row.save()
      print("Label row updated with keypoint instance.")

      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "blueberry_003.png"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Pedicel"  # Name of the keypoint object in your ontology

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

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

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

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

      # Find a keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Keypoint 1 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance01: ObjectInstance = keypoint_ontology_object.create_instance()

      # The x,y coordinates of the keypoint are specified as follows
      keypoint_object_instance01.set_for_frames(
          coordinates=PointCoordinate(
              x=.1,
              y=.1
          ),
          # Add the keypoint to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance01)
      # Keypoint 1 - END

      # Keypoint 2 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance02: ObjectInstance = keypoint_ontology_object.create_instance()

      # The x,y coordinates of the keypoint are specified as follows
      keypoint_object_instance02.set_for_frames(
          coordinates=PointCoordinate(
              x=.2,
              y=.2
          ),
          # Add the keypoint to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance02)
      # Keypoint 2 - END

      # Keypoint 3 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance03: ObjectInstance = keypoint_ontology_object.create_instance()

      # The x,y coordinates of the keypoint are specified as follows
      keypoint_object_instance03.set_for_frames(
          coordinates=PointCoordinate(
              x=.3,
              y=.3
          ),
          # Add the keypoint to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance03)
      # Keypoint 3 - END

      # Save the label row with the keypoint instances
      label_row.save()
      print("Label row updated with keypoint instances.")

      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Pedicel"  # Name of the keypoint object in your ontology

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

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

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

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

      # Find a keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Keypoint 1 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance01: ObjectInstance = keypoint_ontology_object.create_instance()

      coordinates_per_frame = {
          143: PointCoordinate(
              x=.1,
              y=.2
          ),
          144: PointCoordinate(
              x=.11,
              y=.22
          ),
          145: PointCoordinate(
              x=.12,
              y=.23
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          keypoint_object_instance01.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance01)
      # Keypoint 1 - END

      # Keypoint 2 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance02: ObjectInstance = keypoint_ontology_object.create_instance()

      coordinates_per_frame = {
          242: PointCoordinate(
              x=.21,
              y=.22
          ),
          244: PointCoordinate(
              x=.211,
              y=.222
          ),
          246: PointCoordinate(
              x=.212,
              y=.223
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          keypoint_object_instance02.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance02)
      # Keypoint 2 - END

      # Keypoint 3 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance03: ObjectInstance = keypoint_ontology_object.create_instance()

      coordinates_per_frame = {
          343: PointCoordinate(
              x=.31,
              y=.32
          ),
          345: PointCoordinate(
              x=.311,
              y=.322
          ),
          347: PointCoordinate(
              x=.312,
              y=.323
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          keypoint_object_instance03.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance03)
      # Keypoint 3 - END

      # Save the label row with the keypoint instances
      label_row.save()
      print("Label row updated with keypoint instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Bitmask">
    **Example 1:**

    Imports a single bitmask (`Blueberry`) to a single image (`blueberry_003.jpg`). For simplicity, the bitmask covers the entire image (image dimensions: 1254x836).

    **Example 2:**

    Imports three instances (tracking an object across three sequential frames: 156, 157, and 159) of a bitmask (`Blueberry`) to a video (`Blueberries_video.mp4`). For simplicity, the bitmask covers the entire frame (video dimensions: 1920x1080).

    **Example 3:**

    Imports three bitmasks (`Blueberry`) to a single image (`blueberry_003.jpg`). For simplicity, the bitmasks cover the entire image (image dimensions: 1254x836).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 156, 157, 158, object 2 - frames 256, 258, 259, and object 3 - frames 355, 357, 359) of three bitmasks (`Blueberry`) to a video (`Blueberries_video.mp4`). For simplicity, the bitmasks cover the entire frame (video dimensions: 1920x1080).

    <CodeGroup>
      ```python Template theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_HASH = "<unique-project-hash>"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction branch
      DATA_UNIT_TITLE = "<data-unit-name>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<bitmask-object-name>"  # Name of the bitmask object in your ontology

      # Prepare the mask itself.
      # For simplicity, we can just mask the whole image
      # Note: the size of the mask must be identical to the size of the image
      numpy_coordinates = np.ones((<y-axis-value>, <x-axis-value>))  # Replace with actual values

      # Ensure the image is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

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

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

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

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

      # Find a bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      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,
      )

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

      # Save the label row with the bitmask instance
      label_row.save()
      print("Label row updated with bitmask instance.")

      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "blueberry_003.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry"  # Name of the bitmask object in your ontology

      # Prepare the mask itself.
      # For simplicity, we can just mask the whole image
      # Note: the size of the mask must be identical to the size of the image
      numpy_coordinates = np.ones((836, 1254))

      # Ensure the image is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

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

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

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

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

      # Find a bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      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,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the bitmask instance
      label_row.save()
      print("Label row updated with bitmask instance.")

      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry"  # Name of the bitmask object in your ontology

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

      # Ensure the image/frame is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

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

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

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

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

      # Find a bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance: ObjectInstance = bitmask_ontology_object.create_instance()

      # Create and assign the bitmask coordinates for multiple frames
      coordinates_per_frame = {
          156: BitmaskCoordinates(numpy_coordinates),
          157: BitmaskCoordinates(numpy_coordinates),
          158: BitmaskCoordinates(numpy_coordinates),
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          bitmask_object_instance.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

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

      # Save the label row with the bitmask instance 
      label_row.save()
      print("Label row updated with bitmask instance.")

      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "blueberry_003.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry"  # Name of the bitmask object in your ontology

      # Prepare the mask itself.
      # For simplicity, we can just mask the whole image
      # Note: the size of the mask must be identical to the size of the image
      numpy_coordinates = np.ones((836, 1254))

      # Ensure the image is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

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

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

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

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

      # Find a bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Bitmask 1 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance01: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      bitmask_object_instance01.set_for_frames(
          # Create coordinates from provided numpy bitmask
          coordinates=BitmaskCoordinates(numpy_coordinates),
          # Add the bitmask to the first frame
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance01)
      # Bitmask 1 - END

      # Bitmask 2 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance02: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      bitmask_object_instance02.set_for_frames(
          # Create coordinates from provided numpy bitmask
          coordinates=BitmaskCoordinates(numpy_coordinates),
          # Add the bitmask to the first frame
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance02)
      # Bitmask 2 - END

      # Bitmask 3 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance03: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      bitmask_object_instance03.set_for_frames(
          # Create coordinates from provided numpy bitmask
          coordinates=BitmaskCoordinates(numpy_coordinates),
          # Add the bitmask to the first frame
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance03)
      # Bitmask 3 - END

      # Save the label row with the bitmask instances
      label_row.save()
      print("Label row updated with bitmask instances.")

      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry"  # Name of the bitmask object in your ontology

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

      # Ensure the image/frame is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

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

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

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

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

      # Find a bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Bitmask 1 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance01: ObjectInstance = bitmask_ontology_object.create_instance()

      coordinates_per_frame = {
          156: BitmaskCoordinates(numpy_coordinates),
          157: BitmaskCoordinates(numpy_coordinates),
          158: BitmaskCoordinates(numpy_coordinates),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          bitmask_object_instance01.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance01)
      # Bitmask 1 - END

      # Bitmask 2 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance02: ObjectInstance = bitmask_ontology_object.create_instance()

      coordinates_per_frame = {
          256: BitmaskCoordinates(numpy_coordinates),
          258: BitmaskCoordinates(numpy_coordinates),
          259: BitmaskCoordinates(numpy_coordinates),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          bitmask_object_instance02.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance02)
      # Bitmask 2 - END

      # Bitmask 3 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance03: ObjectInstance = bitmask_ontology_object.create_instance()

      coordinates_per_frame = {
          355: BitmaskCoordinates(numpy_coordinates),
          357: BitmaskCoordinates(numpy_coordinates),
          359: BitmaskCoordinates(numpy_coordinates),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          bitmask_object_instance03.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance03)
      # Bitmask 3 - END

      # Save the label row with the bitmask instances
      label_row.save()
      print("Label row updated with bitmask instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Object Primitives">
    <Info>Before you can import Object Primitive labels into Encord, the Object Primitive Template MUST exist in Encord. [Use the UI to create the Object Primitive Template](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#object-primitives) so you can visually inspect the Object Primitive.</Info>

    **Import Object Primitive labels**

    *Example 1*

    Imports a single object primitive (Ontology object = `Strawberry` Object Primitive name = `Triangle`) to a single image (`strawberries_10.jpg`).

    *Example 2*

    Imports three instances (tracking an object across three sequential frames: 163, 164, and 165) of a object primitive (Ontology object = `Strawberry` Object Primitive name = `Triangle`) to a video (`Cherries_video.mp4`).

    *Example 3*

    Imports three object primitives (Ontology object = `Strawberry` Object Primitive name = `Triangle`) to a single image (`strawberries_10.jpg`).

    *Example 4*

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 173, 174, 175, object 2 - frames 183, 184, 185, and object 3 - frames 193, 194, 195) of three object primitives (Ontology object = `Strawberry` Object Primitive name = `Triangle`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Import Skeleton Template theme={"dark"}
      # 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 = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_HASH = "<unique-project-hash>"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction branch
      DATA_UNIT_TITLE = "<name-of-data-unit>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<name-of-object-in-ontology>"  # Name of the object in your ontology
      SKELETON_TEMPLATE_NAME = "<name-of-object-primitive>"  # 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 predictions are to be added
      project: Project = user_client.get_project(PROJECT_HASH)

      # Specify the data unit to label in the given branch
      label_row = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Filter by prediction 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]

      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance: ObjectInstance = skeleton_ontology_object.create_instance()

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]
      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.x0, y=0.y0,  # Replace with actual coordinates
              name='point_0',
              color='#000000',
              value="point_0",
              feature_hash=skeleton_hashes[0]
          ),
          SkeletonCoordinate(
              x=0.x1, y=0.y1,  # Replace with actual coordinates
              name='point_1',
              color='#000000',
              value="point_1",
              feature_hash=skeleton_hashes[1]
          ),
          SkeletonCoordinate(
              x=0.x2, y=0.y2,  # Replace with actual coordinates
              name='point_2',
              color='#000000',
              value="point_2",
              feature_hash=skeleton_hashes[2]
          )
      ],
          name="<name-of-object-primitive>"  # Replace with the actual name
      )

      print(skeleton_coordinates)

      # The x,y coordinates of the skeleton are specified as follows
      skeleton_object_instance.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the skeleton instance
      label_row.save()
      print("Label row updated with skeleton instance.")


      ```

      ```python Example 1 theme={"dark"}
      # 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_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"  # Unique project hash
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction 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_HASH)

      # Specify the data unit to label in the given branch
      label_row = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Filter by prediction 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]

      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance: ObjectInstance = skeleton_ontology_object.create_instance()

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]
      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.25, y=0.25, 
              name='point_0', 
              color='#000000', 
              value="point_0", 
              feature_hash=skeleton_hashes[0]
          ), 
          SkeletonCoordinate(
              x=0.35, y=0.25, 
              name='point_1', 
              color='#000000', 
              value="point_1", 
              feature_hash=skeleton_hashes[1]
          ), 
          SkeletonCoordinate(
              x=0.25, y=0.35, 
              name='point_2', 
              color='#000000', 
              value="point_2", 
              feature_hash=skeleton_hashes[2]
          )
      ], 
      name=SKELETON_TEMPLATE_NAME)

      print(skeleton_coordinates)

      # The x,y coordinates of each skeleton vertex are specified as follows
      skeleton_object_instance.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the skeleton instance 
      label_row.save()
      print("Label row updated with skeleton instance.")

      ```

      ```python Example 2 theme={"dark"}
      # 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_HASH = "b45deb4f-0732-4a89-bdc2-c1c345a82c02"  # Unique project hash
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # 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_HASH)

      # Specify the data unit to label in the given branch
      label_row = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Filter by prediction 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]

      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance: ObjectInstance = skeleton_ontology_object.create_instance()

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]

      coordinates_per_frame = {
          163: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          164: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          165: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          )
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          skeleton_object_instance.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

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

      # Save the label row with the skeleton instance
      label_row.save()
      print("Label row updated with skeleton instance.")

      ```

      ```python Example 3 theme={"dark"}
      # 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_HASH = "a4fe6c6a-2a13-4b3d-bd20-13d57421ecbb"  # Unique project hash
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction 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_HASH)

      # Specify the data unit to label in the given branch
      label_row = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Filter by prediction 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()

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]
      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.25, y=0.25, 
              name='point_0', 
              color='#000000', 
              value="point_0", 
              feature_hash=skeleton_hashes[0]
          ), 
          SkeletonCoordinate(
              x=0.35, y=0.25, 
              name='point_1', 
              color='#000000', 
              value="point_1", 
              feature_hash=skeleton_hashes[1]
          ), 
          SkeletonCoordinate(
              x=0.25, y=0.35, 
              name='point_2', 
              color='#000000', 
              value="point_2", 
              feature_hash=skeleton_hashes[2]
          )
      ], 
      name="Triangle")
      print(skeleton_coordinates)

      # Set the skeleton coordinates for the specified frames
      skeleton_object_instance_01.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=135-137, 
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_01)
      # OBJECT PRIMITIVE 1 - END

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

      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.45, y=0.45, 
              name='point_0', 
              color='#000000', 
              value="point_0", 
              feature_hash=skeleton_hashes[0]
          ), 
          SkeletonCoordinate(
              x=0.65, y=0.45, 
              name='point_1', 
              color='#000000', 
              value="point_1", 
              feature_hash=skeleton_hashes[1]
          ), 
          SkeletonCoordinate(
              x=0.45, y=0.65, 
              name='point_2', 
              color='#000000', 
              value="point_2", 
              feature_hash=skeleton_hashes[2]
          )
      ], 
      name="Triangle")
      print(skeleton_coordinates)

      # Set the skeleton coordinates for the specified frames
      skeleton_object_instance_02.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_02)
      # OBJECT PRIMITIVE 2 - END

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

      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.75, y=0.75, 
              name='point_0', 
              color='#000000', 
              value="point_0", 
              feature_hash=skeleton_hashes[0]
          ), 
          SkeletonCoordinate(
              x=0.95, y=0.75, 
              name='point_1', 
              color='#000000', 
              value="point_1", 
              feature_hash=skeleton_hashes[1]
          ), 
          SkeletonCoordinate(
              x=0.75, y=0.95, 
              name='point_2', 
              color='#000000', 
              value="point_2", 
              feature_hash=skeleton_hashes[2]
          )
      ], 
      name="Triangle")
      print(skeleton_coordinates)

      # Set the skeleton coordinates for the specified frames
      skeleton_object_instance_03.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_03)
      # OBJECT PRIMITIVE 3 - END

      # Save the label row with the skeleton instances
      label_row.save()
      print("Label row updated with skeleton instances.")

      ```

      ```python Example 4 theme={"dark"}
      # 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_HASH = "0adfb083-9b69-4a09-8084-7fb432ecdfeb"  # Unique project hash
      PREDICTION_BRANCH_NAME = "my-prediction-branch-I"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # 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_HASH)

      # Specify the data unit to label in the given branch
      label_row = project.list_label_rows_v2(
          branch_name=PREDICTION_BRANCH_NAME,  # Filter by prediction 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]

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

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]

      coordinates_per_frame = { 
          173: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          174: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          175: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          )
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          skeleton_object_instance_01.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_01)
      # Skeleton 1 - END

      # Skeleton 2 - START
      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance_02: ObjectInstance = skeleton_ontology_object.create_instance()

      coordinates_per_frame = { 
          183: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          184: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          185: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          )
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          skeleton_object_instance_02.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_02)
      # Skeleton 2 - END

      # Skeleton 3 - START
      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance_03: ObjectInstance = skeleton_ontology_object.create_instance()

      coordinates_per_frame = { 
          193: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          194: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          195: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          )
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          skeleton_object_instance_03.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_03)
      # Skeleton 3 - END

      # Save the label row with the skeleton instances 
      label_row.save()

      print("Label row updated with skeleton instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Radio Button">
    **Example 1:**

    Imports a radio button classification (`Blueberry or Cherry?`) to a single image (`blueberry_003.jpg`).

    **Example 2:**

    Imports a radio button classification (`Blueberry or Cherry?`) across a range of sequential frames: 193 to 197) to a video (`Blueberries_video.mp4`).

    <CodeGroup>
      ```python Radio Button Template theme={"dark"}
      # 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 = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_HASH = "<unique-project-hash-id>"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction branch
      DATA_UNIT_TITLE = "<data-unit-name>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<classification-name>"  # Name of the classification in your ontology
      RADIO_BUTTON_OPTION_TITLE = "<radio-button-option-title>"  # Title of the radio button option
      RADIO_BUTTON_OPTION = "<radio-button-option>"  # Specify the answer for the radio button option

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

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

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

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

      # Find the radio classification in the project ontology
      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific radio button option
      blueberry_option = radio_ontology_classification.get_child_by_title(
          title=RADIO_BUTTON_OPTION_TITLE, type_=Option
      )

      # Create an instance of the radio classification
      radio_classification_instance = radio_ontology_classification.create_instance()

      # Set the answer for the classification instance
      radio_classification_instance.set_answer(
          answer=RADIO_BUTTON_OPTION
      )

      # Set the classification for the specified frame
      radio_classification_instance.set_for_frames(
          # Add the classification to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(radio_classification_instance)

      # Save the label row with the classification instance
      label_row.save()

      print("Label row updated with classification instance.")

      ```

      ```python Example 1 theme={"dark"}
      # 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_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction branch
      DATA_UNIT_TITLE = "blueberry_003.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry or Cherry?"  # Name of the classification in your ontology
      RADIO_BUTTON_OPTION_TITLE = "Blueberry"  # Title of the radio button option

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

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

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

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

      # Find the radio classification in the project ontology
      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific radio button option
      blueberry_option = radio_ontology_classification.get_child_by_title(
          title=RADIO_BUTTON_OPTION_TITLE, type_=Option
      )

      # Create an instance of the radio classification
      radio_classification_instance = radio_ontology_classification.create_instance()

      # Set the answer for the classification instance
      radio_classification_instance.set_answer(
          answer=blueberry_option
      )

      # Set the classification for the specified frame
      radio_classification_instance.set_for_frames(
          # Add the classification to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(radio_classification_instance)

      # Save the label row with the classification instance 
      label_row.save()

      print("Label row updated with classification instance.")

      ```

      ```python Example 2 theme={"dark"}
      # 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
      from encord.objects.frames import Range

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"  # Path to your SSH private key
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry or Cherry?"  # Name of the classification in your ontology
      RADIO_BUTTON_OPTION_TITLE = "Blueberry"  # Title of the radio button option

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

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

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

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

      # Find the radio classification in the project ontology
      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific radio button option
      blueberry_option = radio_ontology_classification.get_child_by_title(
          title=RADIO_BUTTON_OPTION_TITLE, type_=Option
      )

      # Create an instance of the radio classification
      radio_classification_instance = radio_ontology_classification.create_instance()

      # Set the answer for the classification instance
      radio_classification_instance.set_answer(
          answer=blueberry_option,
      )

      # Set the classification for the specified frame range
      radio_classification_instance.set_for_frames(
          frames=Range(start=160, end=165),
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(radio_classification_instance)

      # Save the label row with the classification instance
      label_row.save()

      print("Label row updated with classification instance.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Checklist">
    **Example 1:**

    Imports a checklist classification (`Many types of fruit?`) to a single image (`apple_003.jpg`). The selected items from the list are `apple` and `kiwi`.

    **Example 2:**

    Imports a checklist classification (`Many types of fruit?`) across a range of sequential frames: 193 to 197) to a video (`Blueberries_video.mp4`). The selected items from the list are `apple` and `kiwi`.

    <CodeGroup>
      ```python Checklist Template theme={"dark"}
      # 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_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction 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

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

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

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

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

      # Find the checklist classification in the project ontology
      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific options in the checklist
      apple_option = checklist_ontology_classification.get_child_by_title(
          title=APPLE_OPTION_TITLE, type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title=KIWI_OPTION_TITLE, type_=Option
      )

      # Create an instance of the checklist classification
      checklist_classification_instance = checklist_ontology_classification.create_instance()

      # Set the answers for the classification instance
      checklist_classification_instance.set_answer(
          [apple_option, kiwi_option]
      )

      # Set the classification for the specified frame
      checklist_classification_instance.set_for_frames(
          # Add the classification to the image
          frames=177,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(checklist_classification_instance)

      # Save the label row with the classification instance
      label_row.save()

      print("Label row updated with checklist classification instance.")

      ```

      ```python Example 1 theme={"dark"}
      # 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_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction branch
      DATA_UNIT_TITLE = "apple_003.jpg"  # 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

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

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

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

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

      # Find the checklist classification in the project ontology
      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific options in the checklist
      apple_option = checklist_ontology_classification.get_child_by_title(
          title=APPLE_OPTION_TITLE, type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title=KIWI_OPTION_TITLE, type_=Option
      )

      # Create an instance of the checklist classification
      checklist_classification_instance = checklist_ontology_classification.create_instance()

      # Set the answers for the classification instance
      checklist_classification_instance.set_answer(
          [apple_option, kiwi_option]
      )

      # Set the classification for the specified frame
      checklist_classification_instance.set_for_frames(
          # Add the classification to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(checklist_classification_instance)

      # Save the label row with the classification instance
      label_row.save()
      print("Label row updated with checklist classification instance.")

      ```

      ```python Example 2 theme={"dark"}
      # 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
      from encord.objects.frames import Range

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"  # Path to your SSH private key
      PROJECT_HASH = "7d4ead9c-4087-4832-a301-eb2545e7d43b"  # Unique project hash
      PREDICTION_BRANCH_NAME = "<your-prediction-branch-name>"  # Specify your prediction 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

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

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

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

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

      # Find the checklist classification in the project ontology
      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific options in the checklist
      apple_option = checklist_ontology_classification.get_child_by_title(
          title=APPLE_OPTION_TITLE, type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title=KIWI_OPTION_TITLE, type_=Option
      )

      # Create an instance of the checklist classification
      checklist_classification_instance = checklist_ontology_classification.create_instance()

      # Set the answers for the classification instance
      checklist_classification_instance.set_answer(
          [apple_option, kiwi_option]
      )

      # Set the classification for the specified frame range
      checklist_classification_instance.set_for_frames(
          frames=Range(start=193, end=197),
          # Additional fields that can be set optionally:
          manual_annotation=True,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(checklist_classification_instance)

      # Save the label row with the classification instance
      label_row.save()
      print("Label row updated with checklist classification instance.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

This simple example imports a bounding box model prediction to all data units in the prediction branch.

```python Store Predictions Boilerplate theme={"dark"}
# Import dependencies
import os
from encord import EncordUserClient, Project
from encord.objects import LabelRowV2, Object, OntologyStructure, ObjectInstance

from encord.objects.coordinates import BoundingBoxCoordinates, RotatableBoundingBoxCoordinates, PolygonCoordinates, PolylineCoordinates, PointCoordinate, BitmaskCoordinates


# Configuration
SSH_PATH = "file-path-to-your-ssh-key"
PROJECT_HASH = "unique-id-for-project"

# Specify a label_rows_v2 branch name for your predictions.
PREDICTION_BRANCH_NAME = "name-of-your-prediction-branch"

assert SSH_PATH is not None, "SSH path cannot be None"
assert PROJECT_HASH is not None, "Project hash cannot be None"

# Authenticate with Encord
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Access the project and prepare the branch for predictions
project = user_client.get_project(PROJECT_HASH)
prediction_branch_rows = project.list_label_rows_v2(branch_name=PREDICTION_BRANCH_NAME)

if len(prediction_branch_rows) > 0:
  print("Branch is:", prediction_branch_rows[0].branch_name)

ontology_object = project.ontology_structure.objects[0]
with project.create_bundle() as bundle:
    for row in prediction_branch_rows:
        row.initialise_labels(bundle=bundle)

for row in prediction_branch_rows:
    inst = ontology_object.create_instance()
    inst.set_for_frames(
        coordinates=BoundingBoxCoordinates(
            height=0.8,
            width=0.8,
            top_left_x=0.1,
            top_left_y=0.1,
        ),
        # Add the bounding box to the first frame
        frames=0,
        # There are multiple additional fields that can be set optionally:
        manual_annotation=False,
    )
    row.add_object_instance(inst)

with project.create_bundle() as bundle:
    for row in prediction_branch_rows:
        row.save(bundle=bundle)

```

### Import COCO Labels as Predictions

The following code imports COCO labels as predictions.

For more information on [importing COCO labels into Encord](/sdk-documentation/sdk-labels/sdk-import-coco-labels), refer to our documentation.

Replace the following:

* `<private_key_path>` with the file path to your SSH private key.

* `<my-prediction-branch-name>` with the name of your prediction branch.

* `<project_hash>` with the Project ID for your Project.

* `COCOimportfile.json` with the full path of the COCO file containing the predictions you want to import.

```python COCO Label import as Predictions theme={"dark"}

import json
from pathlib import Path
from encord.utilities.coco.datastructure import FrameIndex
from encord import EncordUserClient
from encord.exceptions import OntologyError

# Authenticate client
SSH_PATH = "file-path-to-your-ssh-key"

# Specify a Project to import your predictions to. This Project must already exist in Encord.
PROJECT_HASH = "unique-id-for-project"

# Specify a label_rows_v2 branch name for your predictions.
PREDICTION_BRANCH_NAME = "name-of-your-prediction-branch"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Replace with your project hash
project = user_client.get_project(PROJECT_HASH)

# Load the COCO annotations JSON file
# Replace 'COCOimportfile.json' with the full path to your COCO file
coco_file = Path("COCOimportfile.json")
labels_dict = json.loads(coco_file.read_text())

# Build a mapping from COCO category IDs to the feature hashes in your Encord Ontology. 
category_id_to_feature_hash = {}
ont_struct = project.ontology_structure
for coco_category in labels_dict["categories"]:
    try:
        ont_obj = ont_struct.get_child_by_title(coco_category["name"])
        category_id_to_feature_hash[coco_category["id"]] = ont_obj.feature_node_hash
    except OntologyError:
        print(f"Could not match {coco_category['name']} in the Ontology. Import will crash if these are present.")

# Build a mapping from COCO image IDs to Encord frame indices
# This is only applicable for images, image groups, image sequences, and DICOM series
image_id_to_frame_index = {}
data_title_to_label_row = {lr.data_title: lr for lr in project.list_label_rows_v2()}
for img in labels_dict["images"]:
    lr = data_title_to_label_row[img["file_name"]]

    # Creates a mapping between the COCO image IDs and the corresponding frame indices in Encord
    # In this example, the target frame is 0 because the files in the sample project are single images
    image_id_to_frame_index[img["id"]] = FrameIndex(lr.data_hash, frame=0)

# Import the COCO labels into Encord
project.import_coco_labels(
    labels_dict,
    category_id_to_feature_hash,
    image_id_to_frame_index,
    branch_name=PREDICTION_BRANCH_NAME,
)
```

### Verify Prediction Import

After importing your predictions, verify that your predictions imported.

The following code returns all labels and predictions on all branches.

```python theme={"dark"}

# Import dependencies
from encord import EncordUserClient
import json

SSH_PATH = "file-path-of-your-ssh-key"
PROJECT_HASH = "unique-id-for-your-project"

# Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
project = user_client.get_project(PROJECT_HASH)

# Downloads a local copy of all the labels
# Without the include_all_label_branches flag only the MAIN branch labels export
label_rows = project.list_label_rows_v2(include_all_label_branches=True) 

# Initialize label rows using bundles
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    # Here we have the label row for the branch, but without labels themselves downloaded
    print(f"Title: {label_row.data_title}, branch: {label_row.branch_name}")

    # Print essential label information for all objects
    for object_instance in label_row.get_object_instances():
        print (f"objectHash: {object_instance.object_hash}")
        print (f"Object name: {object_instance.object_name}")
        print (f"featureHash: {object_instance.feature_hash}")
        print (f"uid: {object_instance.ontology_item.uid}")
        print (f"Object color: {object_instance.ontology_item.color}")
        print (f"Ontology shape: {object_instance.ontology_item.shape}")

        # Print the frame number and the location of the object on the frame
        for annotation in object_instance.get_annotations():
            print(f"Frame {annotation.frame} -> {annotation.coordinates}")

        # Print all attributes 
        for attribute in object_instance.ontology_item.attributes:
            print (attribute, object_instance)

    # Print all essential classification information
    for classification_instance in label_row.get_classification_instances():
        print (f"classificationHash: {classification_instance.classification_hash}")
        print (f"Classification name: {classification_instance.classification_name}")
        print (f"featureHash: {classification_instance.feature_hash}")
        print (f"Classification answer: {classification_instance.get_answer().value}")
        print (f"Classification answer hash: {classification_instance.get_answer().feature_node_hash}")


        # Print the frame number(s) that a classification appears on
        for annotation in classification_instance.get_annotations():
            print(f"Classification appears on frame: {annotation.frame}")

```

### End-to-End Prediction Import Example

We provide an end-to-end example using a Jupyter Notebook [here](https://colab.research.google.com/drive/1UYUBkiqanTdhjE37Pj0ArVFn_x0BiJk8?usp=sharing).

## 2. Analyze the Predictions

Encord must analyze the predictions before you can view the predictions.

1. Navigate to the **Explore** tab of your Project.
2. Navigate to **Predictions** > **Prediction** > **Manage**.
3. Click **Analyze** on the prediction set you want to analyze.
4. Specify whether you want to import **Strict Match** or **Partial Match** predictions.

<Warning>
  DO NOT click **Import** on more than one prediction set at a time.

  <img />
</Warning>

![Analyze Predictions](https://storage.googleapis.com/docs-media.encord.com/static/img/analyze-predictions.png)

### Strict Match Predictions

All attributes are matched. This mode makes the most comprehensive comparison. A prediction is considered as a true positive only if an exact match of all attributes matches with the ground truth.

![Strict match](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-predictions-strict-match.png)

### Partial Match Predictions

Only attributes provided in the prediction are compared with the ground truth. Any missing attributes in the prediction, but present in the ground truth, have no impact on the outcome of the prediction.

![Partial Match](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-predictions-partial-match.png)

## 3. Select the Predictions

Once analysis completes:

1. Navigate to **Predictions** > **Prediction**.
2. Select the prediction set you want to view from the dropdown.

<div>
  <img />
</div>

## Delete Prediction Sets

1. Navigate to the **Explore** tab of your Project.
2. Navigate to **Predictions** > **Prediction** > **Manage**.
3. Click the ellipsis icon in the **Actions** column.
4. Click **Delete**.

<div>
  <img />
</div>


# Model Predictions & Evaluation
Source: https://docs.encord.com/platform-documentation/Validation/active-how-to/active-model-predictions-eval



<Note>
  Predictions must be **[imported to
  Active](/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud)**,
  before you can use the Predictions feature on the *Explorer* page and the
  *Model Evaluation* page.
</Note>

Encord Active enables you to visualize the important performance metrics (Average-Precision (mAP), Average-Recall (mAR), F1, True Positive Count, False Positive Count, False Negative Count) for your model. Performance metrics can be visualized based on different classes and intersection-over-Union (IoU) thresholds.

## Model Prediction Support

<table>
  <thead>
    <tr>
      <th>Prediction Type</th>
      <th>Support</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Bounding Box</td>
      <td>Full support</td>
    </tr>

    <tr>
      <td>Rotatable Bounding Box</td>
      <td>Full support</td>
    </tr>

    <tr>
      <td>Polygon</td>
      <td>Full support</td>
    </tr>

    <tr>
      <td>Bitmask</td>
      <td>Full support</td>
    </tr>

    <tr>
      <td>Polyline</td>
      <td>TP and FP support coming soon</td>
    </tr>

    <tr>
      <td>Keypoint</td>
      <td>TP and FP support coming soon</td>
    </tr>
  </tbody>
</table>

Dragging the IOU slider changes the scores.
You can also choose to see the aggregate score for certain classes by selecting them in the drop-down.

## How are Prediction Metrics calculated?

Model performance metrics—such as mAP, mAR, Accuracy, and F1-score—and prediction types (True Positive, False Positive, False Negative) are computed for bounding boxes, polygons (segmentations), and bitmasks. Annotate's labels are treated as the **ground truth** for evaluating your imported predictions.

1. **Label Rendering**: Ground-truth labels are rendered into bitmasks, and all IoU (Intersection over Union) calculations are performed on these bitmasks.

2. **Prediction Matching**: Each prediction is matched to the closest ground-truth label based on IoU.

3. **Confidence Filtering**: Predictions with confidence scores below the specified threshold are discarded.

4. **IoU Thresholding**: For a ground-truth label, the prediction with the **highest confidence** and an IoU exceeding the threshold is selected as the **True Positive (TP)**. If no such prediction exists, no TP is assigned for that ground-truth label.

5. **False Positives (FP)**: Predictions that are not matched to any ground-truth label are classified as False Positives.

<Info>
  When multiple predictions are associated with a single ground-truth label, only one can be marked as the True Positive (TP). The prediction with the **highest confidence** among those exceeding the IoU threshold is chosen.

  This ensures a strict **one-to-one relationship** between ground-truth labels and True Positives.
</Info>

***

### Important Information

Before going any further, you need to be aware of the differences in behavior between pycoco/TorchMetrics map calculations and Encord's.

The comparisons here were done using 'torchmetrics=1.2.1', 'pycocotools=2.0.6', and Encord Active.

**Difference 1**

TorchMetrics ignores a class in the mAP calculation (average AP over classes), if there are no ground truth labels of that class in all the images being looked at. Active includes classes in the mAP calculation even if there are no ground truth labels of that class in all the images being looked at

Why did we do this? Because Encord Active is inherently dynamic and meant for decomposing model performance based on arbitrary data subsets. This makes model performance more transparent because predictions are not excluded from the performance scores.

**Difference 2**

There is a slight difference in the TP matching algorithm. Encord does not have a prediction match against a different ground truth with a smaller IOU than the initial candidate ground truth if some other prediction with higher confidence matches as a true-positive against that original ground truth, but torchmetrics does. This can result in differences compared to TorchMetrics. The differences become apparent with smaller IOU thresholds, IOU values closer to 1.0 should have a progressively smaller divergence approaching 0 when very close to 1.0.

Why did we do this? The difference results in performance improvements when dynamically assigning prediction true-positives depending on the selected IOU threshold.

## Model Performance

**Model Performance - Summary**

![Model Performance](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-summary.png)

**Model Performance - Outcome**

![Model Performance](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-outcome-01.png)

**Model Performance - Average Precision**

![Model Avg Precision](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-avg-accuracy.png)

**Model Performance - Precision**

![Model Precision](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-precision-01.png)

**Model Performance - Recall**

![Model Recall](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-val-recall.png)

**Model Performance - F1 Score**

![Model F1 Score](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-f1.png)

**Model Performance - Metric Correlation**

Specifies the impact specific data and label metrics have on your model performance.

<Info>
  The Impact % is derived from the [Pearson correlation coefficient](https://en.wikipedia.org/wiki/Pearson_correlation_coefficient) between two values:

  1. isTruePositive (converted from a boolean to an integer: true = 1, false = 0)

  2. The corresponding metric value.

  This correlation measures how strongly the metric is associated with the likelihood of a prediction being a true positive.

  * A positive correlation means higher metric values are linked to a higher chance of true positives.
  * A negative correlation means higher metric values are linked to a lower chance of true positives.

  The absolute value of the correlation is used when calculating the final Impact %, so both strong positive and strong negative relationships are considered equally impactful.
</Info>

![Model Metric Correlation](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-met-corr.png)

**Model Performance - Metric Performance**

![Model Metric Performance](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-met-perf.png)

**Model Performance - Precision-Recall Curve**

![Model Precision-Recall Curve](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-prc.png)

**Model Performance - Average IOU**

![Model Average IOU](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-avg-iou.png)

**Model Performance - IOU Distribution**

![Model IOU Distribution](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-iou-distrib.png)

**Model Performance - Confusion Matrix**

![Model Confusion Matrix](https://storage.googleapis.com/docs-media.encord.com/static/img/active/filters-labels-metrics/active-model-eval-confusion-matrix.png)

### Object Confusion Matrix Matching Algorithm

The Object Confusion Matrix uses a distinct matching algorithm compared to other platform metrics. Here's how it differs:

* **Standard Platform Matching**: For most metrics, the matching algorithm processes data item by item and class by class:

  * Labels and predictions are grouped by class
  * Only labels/predictions within the same class are compared
  * This approach is essential for standard object detection workflows

* **Confusion Matrix Matching**: For the object confusion matrix:
  * All ground truths and predictions are processed together, regardless of class
  * The matching algorithm receives the complete set of labels and predictions
  * This approach helps evaluate model performance in multi-class scenarios
  * Enables identification of cross-class confusion and areas needing improvement

<Info>
  The matching algorithm can be viewed as a black box that takes ground truths
  and predictions as input and outputs True Positives (TP), False Positives
  (FP), and False Negatives (FN).
</Info>


# Embedding Plots
Source: https://docs.encord.com/platform-documentation/Validation/embeddings-plots-validation



The embedding plot is a 2D visualization of your high-dimensional data, where proximity between points indicates similarity. This makes it easy to spot clusters, outliers, and patterns at a glance.

<Info>
  You can draw a rectangular selection on the plot to isolate and explore a specific subset of data points. Use the *Order by* drop-down to switch the visualization between data and label embeddings.
</Info>

## Calculate Metrics and Embeddings

<iframe title="YouTube video player" />

1. Navigate to **Projects**.

2. Open the **Explore** tab.

3. Click **Metrics & Embeddings**.

4. Click **Compute** for either option.

5. Specify the following:

   * **Similarity & Natural language search and quality metrics:** Enable to compute embeddings and quality metrics. Access quality metrics for filtering and sorting.
   * **Select embeddings:** Default embeddings are computed by Encord. Alternatively, import and select your own custom embeddings.
   * **Embeddings plot, Diversity and Uniqueness metrics:** Enable to compute UMAP reduction to generate 2D embeddings plots to visualize your data. Also access diversity and uniqueness metrics for curation.

6. Click **Start computation**.

## Using Embedding Plots

<Info>
  To use embedding plots for label validation, you must [calculate metrics and embeddings](/platform-documentation/Validation/label-validation-basics#compute-metrics-and-embeddings).
</Info>

<iframe title="YouTube video player" />

1. Navigate to **Projects**

2. Open the **Explore** tab.

3. Click **Frames** or **Labels**.

4. Click the **Embeddings View** icon.

<Tip>
  * Use the <kbd>V</kbd> + <kbd>E</kbd> shortcut to access the Embeddings View.
  * In addition to selecting points within a rectangular area, you can use filters (but not sort or natural language or image search) on the data or labels.
</Tip>

**Data Embedding Plot**

<iframe title="YouTube video player" />

**Label Embedding Plot**

<iframe title="YouTube video player" />


# Label Validation Basics
Source: https://docs.encord.com/platform-documentation/Validation/label-validation-basics



## Explorer Access by Role

<Note>
  The **Explore** tab is available on Workflow projects only. ManualQA projects do not provide Explore tab access for any role.
</Note>

Users with the **Viewer** role on a Workflow project can now open the **Explore** tab and browse the Explorer in read-only mode. Viewers can access the grid, analytics, and embeddings views and apply existing filters, but Encord hides all mutation affordances for Viewers.

The following actions are **not available** to Viewers:

* Bulk actions (priority, collections, bulk classify, change class, delete labels, export CSV)
* Creating, editing, or deleting collections
* Adding or removing items from collections (collection tags remain visible)
* Creating, editing, deleting, or saving filter presets (including the `Alt+P` keyboard shortcut)
* Importing or deleting prediction sets (**Manage** button is hidden)

Viewers **can** post comments and raise issues in the Explorer, consistent with platform-wide permissions.

For the full role permissions matrix, see [Roles and Permissions](/platform-documentation/Annotate/roles-and-permissions).

## Compute Metrics and Embeddings

<Tip>
  Computing metrics and embeddings is required to use Similarity Search, Natural Language Search, Quality Metric filters, and Embeddings Analysis.
</Tip>

1. Navigate to **Projects**.
2. Open the **Explore** tab.
3. Hover over **Metrics & Embeddings**
4. Click **Compute**.

<div>
  <img />
</div>

5. Configure the computation:
   * Select whether you want Similarity & Natural language search and quality metrics
   * Select which embeddings to use.
   * Select whether you want the embeddings plot, and Diversity and Uniqueness metrics.

6. Click **Start computation**.

<div>
  <img />
</div>

## Quality Metrics

<Warning>
  Quality metrics are only calculated when you [compute metrics and embeddings](#compute-metrics-and-embeddings).
</Warning>

Quality metrics evaluate your data, labels, and model predictions, forming the foundation of effective data curation. They provide meaningful ways to surface, rank, and explore your data — helping you identify issues, spot patterns, and make informed decisions about what to curate, fix, or prioritize.

<Note>
  If you add a large amount of new data to a folder, existing uniqueness and diversity scores may no longer reflect the full dataset. You can [recompute these metrics](/platform-documentation/Curate/curation-basics#quality-metrics#recompute-quality-metrics) at any time to bring them up to date.
</Note>

<b>Video Quality Metrics:</b> Video quality metrics must be calculated by upgrading your folder. Examples include Area, Clip duration, Frames per second, Number of frames.

<b>Data Quality Metrics:</b> Data quality metrics must be calculated by upgrading your folder. Examples include Area, Frame number, Random value.

<AccordionGroup>
  <Accordion title="Data Quality Metrics">
    For more detailed information on Data Quality Metrics, refer to the Data Quality Metrics documentation.

    | Title                                                                                                                                           | Metric Type | Ontology Type                                                                                                      |
    | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
    | **Area** - <small>Ranks images by their area (width/height).</small>                                                                            | `image`     |                                                                                                                    |
    | **Aspect Ratio** - <small>Ranks images by their aspect ratio (width/height).</small>                                                            | `image`     |                                                                                                                    |
    | **Blue Value** - <small>Ranks images by how blue the average value of the image is.</small>                                                     | `image`     |                                                                                                                    |
    | **Brightness** - <small>Ranks images by their brightness.</small>                                                                               | `image`     |                                                                                                                    |
    | **Contrast** - <small>Ranks images by their contrast.</small>                                                                                   | `image`     |                                                                                                                    |
    | **Diversity** - <small>Forms clusters based on the Ontology and ranks images from easy samples to annotate to hard samples to annotate.</small> | `image`     |                                                                                                                    |
    | **Frame Number** - <small>Selects images based on a specified range.</small>                                                                    | `image`     |                                                                                                                    |
    | **Green Value** - <small>Ranks images by how green the average value of the image is.</small>                                                   | `image`     |                                                                                                                    |
    | **Height** - <small>Ranks images by the height of the image.</small>                                                                            | `image`     |                                                                                                                    |
    | **Object Count** - <small>Counts number of objects in the image.</small>                                                                        | `image`     | `bounding box`, `checklist`, `point`, `polygon`, `polyline`, `radio`, `rotatable bounding box`, `skeleton`, `text` |
    | **Object Density** - <small>Computes the percentage of image area that is occupied by objects.</small>                                          | `image`     | `bounding box`, `polygon`, `rotatable bounding box`                                                                |
    | **Randomize Images** - <small>Assigns a random value between 0 and 1 to images.</small>                                                         | `image`     |                                                                                                                    |
    | **Red Value** - <small>Ranks images by how red the average value of the image is.</small>                                                       | `image`     |                                                                                                                    |
    | **Sharpness** - <small>Ranks images by their sharpness.</small>                                                                                 | `image`     |                                                                                                                    |
    | **Uniqueness** - <small>Finds duplicate and near-duplicate images.</small>                                                                      | `image`     |                                                                                                                    |
    | **Width** - <small>Ranks images by the width of the image.</small>                                                                              | `image`     |                                                                                                                    |
  </Accordion>

  <Accordion title="Label Quality Metrics">
    Label Quality Metrics are used for sorting data, filtering data, and data analytics.

    | Title                                                                                                              | Metric Type         | Ontology Type                                                                        |
    | ------------------------------------------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------ |
    | **Absolute Area** - <small>Computes object size in amount of pixels.</small>                                       | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Aspect Ratio** - <small>Computes aspect ratios of objects.</small>                                               | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Blue Value** - <small>Ranks annotated objects by how blue the average value of the object is.</small>            | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Border Proximity** - <small>Ranks annotations by how close they are to image borders.</small>                    | `image`             | `bounding box`, `point`, `polygon`, `polyline`, `rotatable bounding box`, `skeleton` |
    | **Brightness** - <small>Ranks annotated objects by their brightness.</small>                                       | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Broken Object Tracks** - <small>Identifies broken object tracks based on object overlaps.</small>                | `sequence`, `video` | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Classification Quality** - <small>Compares image classifications against similar images.</small>                 | `image`             | `radio`                                                                              |
    | **Confidence** - <small>The confidence that an object was annotated correctly.</small>                             | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Contrast** - <small>Ranks annotated objects by their contrast.</small>                                           | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Green Value** - <small>Ranks annotated objects by how green the average value of the object is.</small>          | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Height** - <small>Ranks annotated objects by the height of the object.</small>                                   | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Inconsistent Object Class** - <small>Looks for overlapping objects with different classes across frames.</small> | `sequence`, `video` | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Inconsistent Track ID** - <small>Looks for overlapping objects with different track IDs across frames.</small>   | `sequence`, `video` | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Label Duplicates** - <small>Ranks labels by how likely they are to represent the same object.</small>            | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Missing Objects** - <small>Identifies missing objects based on object overlaps.</small>                          | `sequence`, `video` | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Object Classification Quality** - <small>Compares object annotations against similar image crops.</small>        | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Occlusion Risk** - <small>Tracks objects and detects outliers in videos.</small>                                 | `sequence`, `video` | `bounding box`, `rotatable bounding box`                                             |
    | **Polygon Shape Anomaly** - <small>Calculates potential outliers by polygon shape.</small>                         | `image`             | `polygon`                                                                            |
    | **Randomize Objects** - <small>Assigns a random value between 0 and 1 to objects.</small>                          | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Red Value** - <small>Ranks annotated objects by how red the average value of the object is.</small>              | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Relative Area** - <small>Computes object size as a percentage of total image size.</small>                       | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Sharpness** - <small>Ranks annotated objects by their sharpness.</small>                                         | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
    | **Width** - <small>Ranks annotated objects by the width of the object.</small>                                     | `image`             | `bounding box`, `polygon`, `rotatable bounding box`                                  |
  </Accordion>

  <Accordion title="Video Quality Metrics">
    | Title                                                                                                                                           | Metric Type | Ontology Type                                                                                                      |
    | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
    | **Area** - <small>Ranks videos by their area (width/height).</small>                                                                            | `video`     |                                                                                                                    |
    | **Aspect Ratio** - <small>Ranks videos by their aspect ratio (width/height).</small>                                                            | `video`     |                                                                                                                    |
    | **Blue Value** - <small>Ranks videos by how blue the average value of the video is.</small>                                                     | `video`     |                                                                                                                    |
    | **Brightness** - <small>Ranks videos by their brightness.</small>                                                                               | `video`     |                                                                                                                    |
    | **Clip Duration** - <small>Ranks videos based on the video's duration.</small>                                                                  | `video`     |                                                                                                                    |
    | **Contrast** - <small>Ranks videos by their contrast.</small>                                                                                   | `video`     |                                                                                                                    |
    | **Diversity** - <small>Forms clusters based on the ontology and ranks videos from easy samples to annotate to hard samples to annotate.</small> | `video`     |                                                                                                                    |
    | **Frame Number** - <small>Selects videos based on a specified range.</small>                                                                    | `video`     |                                                                                                                    |
    | **Frame Label Count**                                                                                                                           | `video`     |                                                                                                                    |
    | **Frames Per Second**                                                                                                                           | `video`     |                                                                                                                    |
    | **Green Value** - <small>Ranks videos by how green the average value of the video is.</small>                                                   | `video`     |                                                                                                                    |
    | **Height** - <small>Ranks videos by the height of the video.</small>                                                                            | `video`     |                                                                                                                    |
    | **Instance Label Count** - <small>Ranks videos by the number of unique objects in the video.</small>                                            | `video`     | `bounding box`, `checklist`, `point`, `polygon`, `polyline`, `radio`, `rotatable bounding box`, `skeleton`, `text` |
    | **Red Value** - <small>Ranks videos by how red the average value of the video is.</small>                                                       | `video`     |                                                                                                                    |
    | **Sharpness** - <small>Ranks videos by their sharpness.</small>                                                                                 | `video`     |                                                                                                                    |
    | **Uniqueness** - <small>Finds duplicate and near-duplicate videos.</small>                                                                      | `video`     |                                                                                                                    |
    | **Unlabelled Frames (%)** - <small>Ranks videos based on the percentage of unlabelled frames in the video.</small>                              | `video`     |                                                                                                                    |
    | **Unlabelled Frames (#)** - <small>Ranks videos based on the number of unlabelled frames in the video.</small>                                  | `video`     |                                                                                                                    |
    | **Width** - <small>Ranks videos by the width of the video.</small>                                                                              | `video`     |                                                                                                                    |
  </Accordion>

  <Accordion title="Model Quality Metrics">
    Model quality metrics help you evaluate your data and labels based on a trained model and imported model predictions.

    **Acquisition Functions**

    Acquisition functions are a special type of model quality metric, primarily used in active learning to score data samples according to how informative they are for the model, enabling smart labeling of unannotated data.

    | Title                                                                               | Metric Type | Data Type |
    | ----------------------------------------------------------------------------------- | ----------- | --------- |
    | **Entropy** - <small>Ranks images by their entropy.</small>                         | `image`     |           |
    | **Least Confidence** - <small>Ranks images by their least confidence score.</small> | `image`     |           |
    | **Margin** - <small>Ranks images by their margin score.</small>                     | `image`     |           |
    | **Variance** - <small>Ranks images by their variance.</small>                       | `image`     |           |
    | **Mean Object Score** - <small>Ranks images by their average object score.</small>  | `image`     | `object`  |
  </Accordion>
</AccordionGroup>

## Collections

Collections are saved groups of data units or labels that let you curate subsets of your data and perform bulk actions on them, such as sending items to annotation, running bulk classifications, or exporting a curated Dataset.

In the Explorer filter toolbar, each collection has a **...** (three-dot) menu that displays the collection name and its unique collection ID. Click the copy icon next to the ID to copy it to your clipboard — useful for API calls, support requests, or cross-referencing collections. Actions in this menu are organized into logical groups (navigate, manage, data, workflow, and danger) separated by dividers, making it faster to locate the right action. Empty groups are hidden automatically so no stray dividers appear.

## Analytics View

Use the Analytics view to display Metric Correlation and prediction distribution for your ML model. Prediction distribution provides class and underrepresented class data. You can adjust the X and Y values on the Metric Correlation across a number of data and label metrics.

You can create custom analytics dashboards from the **Analytics View** using **Distribution** and **Correlation** charts. The Analytics View includes a **Slice strip** at the top of the canvas that lets you define named filter sets called slices and compare data distributions across multiple cohorts simultaneously.

<div>
  <img />
</div>

### Cohort Comparison via Slices

Encord lets you define named filter sets called **slices** and compare data distributions across multiple cohorts simultaneously on the same chart. Each slice appears as its own series, enabling side-by-side comparison without manually switching filters.

#### The Slice Strip

A **Slice strip** appears at the top of the Analytics canvas and is the primary control for creating and managing slices. It contains:

* **All data** — an unfiltered baseline chip that is always present. You cannot remove or rename it.
* **Current filters** — a transient chip that appears automatically whenever you have active toolbar filters. It shares the same filter set as the grid view, and has a dashed border to distinguish it from saved slices. Clicking it opens the **Current filters** editor.
* **User-defined slices** — named slices you create by clicking **+ Add slice**.
* **Add new chart** — opens a menu to add a **Distribution** or **Correlation** chart to the canvas. This button replaces the former floating bottom-right button.
* **How it works?** — opens an illustrated modal explaining bucket-width snapping, shared-grid rebinning, and how hiding slices affects charts.

<Note>
  Slices are saved to your browser's local storage, keyed by project. They persist across page reloads but are specific to your browser and are not shared with other collaborators.
</Note>

#### Adding and Managing Slices

<Steps>
  <Step title="Add a slice">
    Click **+ Add slice** in the Slice strip. Encord creates a new empty slice and immediately opens the slice editor popover.
  </Step>

  <Step title="Configure the slice">
    In the slice editor, you can:

    * Rename the slice.
    * Choose a color for the slice's series on charts.
    * Set filters using the filter controls and any saved presets to define the cohort.
    * Click **View in Explorer** to apply the slice's filters as the active filter set and navigate to the grid view.
  </Step>

  <Step title="Save the slice">
    Close the slice editor popover. The slice chip appears in the Slice strip and Encord immediately adds it as a series on all distribution charts.
  </Step>

  <Step title="Edit a slice">
    Click the pencil icon on a slice chip to reopen its editor and change its name, color, or filters.
  </Step>

  <Step title="Hide a slice from charts">
    Click the eye icon on a slice chip to hide that slice. Encord excludes it from chart queries and the comparison footer entirely, not just from the visual display. Click the icon again to restore it.
  </Step>

  <Step title="Remove a slice">
    Click the remove icon on a slice chip to delete it permanently.
  </Step>
</Steps>

#### Multi-Series Distribution Charts

When you have saved slices or an active **Current filters** set, distribution charts render as multi-series grouped bar charts — one bar series per visible slice. The **All data** baseline always appears as a series unless you hide it. A **comparison footer** below each chart mirrors the visible series from the Slice strip with a per-cohort count summary.

Each distribution chart also offers two bucket alignment modes, which you can toggle directly on the chart:

| **Mode**    | **Description**                                                                                                                                    |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Aligned** | Rebins all series onto a shared bucket grid so bars align side by side for direct comparison.                                                      |
| **Native**  | Keeps each series' own backend bucket edges as translucent overlapping bars on a linear axis, preserving each cohort's natural distribution shape. |

#### Empty Analytics Dashboard

When the Analytics canvas has no charts, Encord displays a headline and quick-start cards. Click a card to add a **Distribution** or **Correlation** chart directly to the canvas.

<Warning>
  The following do not support multi-series slice comparison and continue to use a single-series chart:

  * File and frame client metadata distributions (some metadata endpoints)
  * Feature-hash attribute distributions
  * Text-search boolean distributions
  * Prediction mode distributions
  * Correlation charts (scatter plots), which always display data for the current unfiltered view
</Warning>

### Distribution charts

Distribution charts display distributions and summaries of the selected metrics and custom metadata.

Here are some examples:

* Data unit: Frame number, random value, area
* Metadata: Enum with their enum options, numeric, date time, and boolean

<Note>`varchar` (previously `string`), `text` (previously `long_string`), and `uuid` are NOT SUPPORTED for use in Distribution charts.</Note>

When slices are present or active filters exist, Distribution charts render as multi-series grouped bar charts (see **Cohort Comparison via Slices** above for details on slices and bucket alignment modes).

![Add Distribution chart](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-add-distribution-chart.gif)

### Correlation charts

Correlation charts display a scatter plot of two attributes to show correlation within your current filtered view. Correlation charts require numeric data.

<Note>Distribution charts support a number of custom metadata types, however Correlation charts ONLY SUPPORT `numeric` custom metadata.</Note>

<Note>Correlation charts always display data for the current unfiltered view and do not support multi-series slice comparison.</Note>

![Add Correlation chart](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-add-correlation-chart.gif)

### Stat tiles

Stat tiles display a horizontal bar chart with one bar per slice. Each bar's length is proportional to the item count of the largest slice currently in view, so you can compare slice sizes at a glance even when a small slice sits alongside a much larger baseline. The right-hand label shows the item count and the percentage of the baseline count.

Bar order runs from top to bottom: the unfiltered **All data** baseline appears first, followed by any active toolbar filter slice, then your user-defined slices.

<Note>When an embedding-distance filter is active, Stat tiles cannot retrieve a count for the affected slice and displays a dash (`-`) in place of the count.</Note>

Stat tiles defaults to small (S) size on the dashboard canvas. Encord saves your chart configuration across reloads.

### Metadata coverage

Metadata coverage displays one row per metadata key. Each row contains one horizontal bar per slice, showing how many items in that slice have that key populated. All bars share a common scale — the highest single-slice count across all displayed rows — so you can compare coverage both across slices within a row and across rows for the same slice.

Use this chart to identify which metadata fields carry signal (high coverage) and which are sparsely filled across your dataset slices.

**Selection modes**

Metadata coverage offers two ways to choose which keys to display:

* **Auto mode** (default) — Encord automatically shows the top 20 keys by total coverage across all slices.
* **Explicit mode** — You select specific keys using the **Keys** multi-select dropdown. Selecting or removing any key switches the chart into explicit mode.

To remove an individual key from the chart, click the **×** button on that key's row. To return to auto mode, click the **Reset to top N** link in the chart caption.

Metadata coverage supports both file-level and frame-level metadata domains.

<Note>If your project has no client metadata schema, or if the data query fails, Metadata coverage displays clearly labeled example data so the chart remains usable. The chart caption indicates when example data is showing.</Note>

Metadata coverage defaults to medium (M) size on the dashboard canvas. Encord saves your chart configuration — including any explicit key selections — across reloads.

## Project Overview summary cards

The **Overview** tab of a workflow Project displays a set of summary cards that give you an at-a-glance view of Project health and progress.

<Note>All summary cards described below are hidden for labeling-services-only Projects.</Note>

### Stat cards

A row of three compact stat cards appears at the top of the overview:

* **Tasks completed** — shows completed tasks out of the total task count, with a Project status selector in the footer.
* **Time spent** — shows the total time annotators have spent on the Project. When time data is available, a **Show breakdown** link navigates to the **Collaborators** tab in Analytics.
* **Opened issues** — shows the number of currently open (unresolved) issues. When open issues exist, a **Show tasks** link navigates to the Project queue filtered to tasks with unresolved issues.

### Class distribution card

The **Class distribution** card shows a horizontal bar chart of label instances by class. It displays the top 5 and bottom 5 classes by instance count. When more classes exist between those two groups, the card shows a truncation indicator for the hidden middle classes.

* The card subtitle shows the total number of label instances (for example, "1,234 label instances").
* When no label instances exist yet, the card displays "Instance labels by class will appear here."
* When data is available, a **Show analytics** link navigates to the **Labels** tab in Analytics. This link is hidden when the card is empty.

### Top issue tags card

The **Top issue tags** card replaces the previous Issues overview card. It shows up to 10 issue tags ranked by frequency, displayed as amber-colored horizontal bars. The card subtitle shows the total number of issue tags created for the Project.

* An info popover on the card explains what issue tags are and links to documentation.
* A **Show analytics** link navigates to the **Issues** tab in Analytics. This link is hidden when the card is empty.
* When no issue tags have been used yet, the card displays "Most common issue tags will appear here" and a **Setup issue tags** link to issue-tag settings.

<Note>Tag bar counts reflect tag-action totals rather than unique issue counts. The count for untagged issues is a frontend approximation and may under-report — it can show 0 even when untagged issues exist.</Note>

### Custom Analytics Dashboard

<Tip>Before creating a custom analytics dashboard, we recommend having custom metadata available in your data. Custom metadata can make the insights you get from the dashboard much more useful.</Tip>

1. Navigate to **Project** > **Explore** and select a folder.

2. Click **Analytics view**.

3. Specify the display criteria for the *Distribution* and *Correlation* cards that display by default.

4. Click **Add chart** to add additional *Distribution* and *Correlation* cards.

5. Specify the display criteria for the added *Distribution* and *Correlation*.

## Crop View

<Note>
  Crop View is only available from the **Labels** page of the **Explore** tab in your Project.
</Note>

The **Labels** page displays all object and classification annotations on your images and video frames. *Crop View* zooms in on each annotated object, making it easier to inspect small or densely annotated regions.

For example, if a blueberry is annotated in an HD video frame containing many blueberries, Crop View off shows the full frame with the annotation highlighted but hard to see. Crop View on zooms directly into the annotated object.

**To turn ON Crop View for all labels:**

1. Navigate to your Project and click **Explore**.

2. Click **Labels**.
   The *Labels* page appears.

3. Click **Display**.
   The *Display* tab appears.

   ![Crop View](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-crop-view.gif)

4. Toggle the Crop View switch.
   Object labels immediately are zoomed in on. Images/video frames with Classifications remain unchanged.

   <Note>Classifications on images/video frames are not affected by the Crop View feature. This is because Classifications apply to the entire image/video frame, while object annotations apply to specific areas/regions of an image/video frame. The following image has a Classification label/annotation `Blueberry or Cherry? Blueberry` and a bitmask object label/annotation `Blueberry`. The bitmask object annotation zooms in, while the classification does not.</Note>

5. Adjust the **Crop View Zoom** as required.


# Custom Embeddings
Source: https://docs.encord.com/platform-documentation/Validation/validation-custom-embeddings



## Default Embeddings

Embeddings are calculated using our purpose-built models, which perform well across a broad range of tasks. For highly specialized domains, custom embeddings may be more appropriate.

Our built-in embeddings power the following features:

* **Natural language search**
* **Image similarity search**
* **Embeddings view**

<Note>Natural language search is also supported with custom embeddings in both **Data** > **Explore** and **Project** > **Explore**. Enabling natural language search for custom embeddings requires additional setup. Contact your Encord representative for help.</Note>

## Custom Embeddings Support

Encord enables the use of custom embeddings for images, image sequences, image groups, and individual video frames. Custom embeddings allow you to incorporate your own feature representations into Encord's platform, enhancing capabilities like similarity search, visualizations, and data filtering. This flexibility supports more advanced workflows and deeper insights tailored to your specific use cases.

## Use Custom Embeddings

To bring your custom embeddings into Encord, you first need to create a key in your metadata schema. After the key is in your schema, you can import your custom embeddings. Custom embeddings can be used for data curation and label validation.

**To use custom embeddings**

1. Create a new `embedding` type in your Schema.
2. Upload your embeddings.
3. Select your custom embeddings from the *Embeddings* view.

<Note>Before you can use embedding plots with your custom embeddings, you need to configure your root Folder in Files.</Note>

### 1. Create New Embedding Type

A key is required in your custom metadata schema for your embeddings. You can use any string as the key for your embeddings. We strongly recommend that you use a string that is meaningful.

If you do not include a key in your metadata schema, your imported embeddings are treated as strings.

<Tip>Embedding key names can contain alphanumeric (a-z, A-Z, 0-1) characters, hyphens, and underscores.</Tip>

Use `add_embedding` to add an embedding to your metadata schema.

<Info>
  We currently support embeddings of:

  * 1 to 4,096 dimensions for data curation.
  * 1 to 2,000 dimensions for label validation.
</Info>

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()


  # Add embedding fields
  metadata_schema.add_embedding('my-test-active-embedding', size=512)
  metadata_schema.add_embedding('my-test-index-embedding', size=<values-from-1-to-4096>)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()


  # Add embedding fields
  metadata_schema.add_embedding('active-embedding-01', size=512)
  metadata_schema.add_embedding('active-embedding-02', size=512)
  metadata_schema.add_embedding('index-embedding-100', size=100)
  metadata_schema.add_embedding('index-embedding-1000', size=1000)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

### 2. Upload Embeddings

With the key in the custom metadata schema ready, we can now import our embeddings.

Custom embedding sizes are flexible and can be set anywhere between 1 and 4096.

You can import embeddings after you have added your data or during your data registration.

<Note>Your key frames (frames specified with or without embeddings) always appear in Encord, regardless of what sampling rate you specify.</Note>

<Tip>Embedding key names can contain alphanumeric (a-z, A-Z, 0-1) characters, hyphens, and underscores.</Tip>

If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

<Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video.</Info>

<AccordionGroup>
  <Accordion title="Import while registering videos">
    #### Import while importing videos

    This JSON file imports embeddings while registering your data with Encord from a cloud integration.

    `config` is optional when importing your custom embeddings:

    ```json theme={"dark"}
    "config": {
        "sampling_rate": "<samples-per-second>",
        "keyframe_mode": "frame" or "seconds",
    },
    ```

    If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

    <Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video.</Info>

    <CodeGroup>
      ```json Import Embeddings Template theme={"dark"}

      {
          "videos": [
              {
                  "objectUrl": "<cloud-file-path-to-your-video-1>",
                  "title": "<title-for-your-video-1>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<samples-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "<cloud-file-path-to-your-video-2>",
                  "title": "<title-for-your-vide-2>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<frames-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "<cloud-path-to-your-video-3>",
                  "title": "<title-for-your-video-3>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<frames-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```

      ```json Example - Simple theme={"dark"}
      {
          "videos": [
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-001.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "111": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "113": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-002.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "157": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "257": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-003.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "11": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "13": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```

      ```json Example - Advanced theme={"dark"}
      {
          "videos": [
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-001.mp4",
                  "title": "awesome-video-001.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "111": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "113": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-002.mp4",
                  "title": "awesome-video-002.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "3",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "157": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "257": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-003.mp4",
                  "title": "awesome-video-003.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "4",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "11": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "13": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update specific videos">
    #### Update specific videos

    <CodeGroup>
      ```python Boilerplate theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

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

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "<data-hash-1>": {
              "$encord": {
                  "frames": {
                      "<frame-number-1>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      },
                      "<frame-number-2>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "<data-hash-2>": {
              "$encord": {
                  "config": {
                      "sampling_rate": <samples-per-second>,  # VIDEO ONLY (optional default = 1 sample/second)
                      "keyframe_mode": "frame" or "seconds",  # VIDEO ONLY (optional default = "frame")
                  },
                  "frames": {
                      "<frame-number-1>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      },
                      "<frame-number-2>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)
      ```

      ```python Example - Simple theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

      # Authentication
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "f2155fa4-6040-408a-84d5-72bacb4f45db": {
              "$encord": {
                  "frames": {
                      "113": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "131": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "f235ad84-f9eb-4dc1-934d-d05e1cd70e59": {
              "$encord": {
                  "frames": {
                      "171": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "231": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)

      ```

      ```python Example - Advanced theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

      # Authentication
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "6b8d797a-4655-43c3-b251-cbd6cc995bc6": {
              "$encord": {
                  "config": {
                      "sampling_rate": 0,  # VIDEO ONLY (optional default = 1 sample/second)
                  },
                  "frames": {
                      "111": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "222": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "d9185f6e-3dbc-443b-bd37-77b2f34f157e": {
              "$encord": {
                  "config": {
                      "sampling_rate": 2,  # VIDEO ONLY (optional default = 1 sample/second)
                      "keyframe_mode": "frame",  # VIDEO ONLY (optional default = "frame")
                  },
                  "frames": {
                      "333": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "444": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Import while registering data units">
    #### Import while importing data units

    This JSON file imports embeddings while registering your data with Encord from a cloud integration.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/data-unit/file-name-01.file-extension",
            "title": "data-unit-title.file-extension",
            "clientMetadata": {"metadata-1": "value", "metadata-2": "value"}
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Example - Simple theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 01",
            "clientMetadata": {
              "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-02.jpg",
            "title": "Blueberry 02",
            "clientMetadata": {
              "embeddings-10": [0.44531257187793305, 0.22303790771089994, 0.1101464760810051, 0.3898273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 03",
            "clientMetadata": {
              "embeddings-10": [0.45631257187793305, 0.23403790771089994, 0.1211464760810051, 0.3678273275803421, 0.06849531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                }
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Example - Advanced theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-01.jpg",
            "title": "Cherry 01",
            "clientMetadata": {
              "Dark": false,
              "Location": "NY",
              "Date": "2024-06-13",
              "ACME Co ID": "8ada6567-c034-4bd4-91d0-04dab5d729d5",
              "Priority": "1",
              "embeddings-10": [
                0.67831257187793305,
                0.32603790771089994,
                0.4341464760810051,
                0.9748273275803421,
                0.23549531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-02.jpg",
            "title": "Cherry 02",
            "clientMetadata": {
              "Dark": false,
              "Location": "NY",
              "Date": "2024-06-13",
              "ACME Co ID": "1262bf57-402e-427c-8c60-276df65513ea",
              "Priority": "1",
              "embeddings-10": [
                0.42531257187793305,
                0.33403790771089994,
                0.5671464760810051,
                0.3688273275803421,
                0.06849531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-03.jpg",
            "title": "Cherry 03",
            "clientMetadata": {
              "Dark": true,
              "Location": "OH",
              "Date": "2024-06-13",
              "ACME Co ID": "3000919f-01e2-4574-a4fd-a2790c4f7b8b",
              "Priority": "2",
              "embeddings-10": [
                0.22231257187793305,
                0.44503790771089994,
                0.7341464760810051,
                0.8368273275803421,
                0.06849531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update specific data units">
    #### Import specific data units

    The custom embeddings format for images, text files, PDFs, and audio files follows the same format as [importing custom metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata#folders-and-custom-metadata).

    ```python theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient
    from encord.http.bundle import Bundle

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

    # Authenticate with Encord using the path to your private key
    user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=SSH_PATH,
    )

    # Define a dictionary with item UUIDs and their respective metadata updates
    updates = {
        "<data-ID-1>": {"<my-embedding>": [1.0, 2.0, 3.0]},
        "<data-ID-2>": {"<my-embedding>": [1.0, 2.0, 3.0]}
    }

    # Use the Bundle context manager
    with Bundle() as bundle:
        # Update the storage items based on the dictionary
        for item_uuid, metadata_update in updates.items():
            item = user_client.get_storage_item(item_uuid=item_uuid)

            # Make a copy of the current metadata and update it with the new metadata
            curr_metadata = item.client_metadata.copy()
            curr_metadata.update(metadata_update)

            # Update the item with the new metadata and bundle
            item.update(client_metadata=curr_metadata, bundle=bundle)

    ```
  </Accordion>
</AccordionGroup>

### 3. Select your Custom Embeddings

After you import your custom embeddings they are available for:

* Filtering using custom embeddings

* Similarity searches using your custom embeddings

* *Embedding* view and 2D plots with selection based workflows

<Note>Before you can use embedding plots with your custom embeddings, you need to configure your root Folder in Files.</Note>

### Compute Metrics and Embeddings

Before you can perform filtering, use similarity searches, or use embedding plots with your custom embeddings, you need to compute Metrics and Embeddings.

<iframe title="YouTube video player" />

1. Navigate to **Projects**.

2. Open the **Explore** tab.

3. Click **Metrics & Embeddings**.

4. Click **Compute** for either option.

5. Specify the following:

   * **Similarity & Natural language search and quality metrics:** Enable to compute embeddings and quality metrics. Access quality metrics for filtering and sorting.
   * **Select embeddings:** Default embeddings are computed by Encord. Alternatively, import and select your own custom embeddings.
   * **Embeddings plot, Diversity and Uniqueness metrics:** Enable to compute UMAP reduction to generate 2D embeddings plots to visualize your data. Also access diversity and uniqueness metrics for curation.

6. Click **Start computation**.

### Filtering with Custom Embeddings

<Info>
  You must calculate metrics and embeddings before you can filter with your custom embeddings.
</Info>

1. Click the **Filter** dropdown or press <kbd>F</kbd>.

   ![Filter by custom embeddings](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-filter-by-custom-embeddings.gif)

2. Click **Custom Embeddings** from the menu.

3. Select your custom embedding to filter your data.

4. Select **True** to display images, frames, or videos with the custom embeddings.

### Similarity Searches with Custom Embeddings

<Info>
  You must calculate metrics and embeddings before using the similarity search with your custom embeddings.
</Info>

1. Click the **Embeddings** icon in the Explorer.

   The Embeddings screen appears.

2. Select the embedding you want to use from the **Select custom embeddings** menu.

   <div>
     <img />
   </div>

3. Click the **Grid** icon.

4. Hover over an image or frame with the custom embedding.

   <div>
     <img />
   </div>

5. Click the **Similarity Search** icon.
   Images and Frames sort according to similarity.

#### Adjust Similarity Search Distance

1. Click the **Embeddings** icon in the Explorer.
   The Embeddings screen appears.

2. Select the embedding you want to use from the **Select custom embeddings** menu.

   <div>
     <img />
   </div>

3. Click the **Grid** icon.

4. Hover over an image or frame with the custom embedding.

   <div>
     <img />
   </div>

5. Click the **Similarity Search** icon.
   Images and Frames sort according to similarity AND a *Distance* filter appears.

   ![Distance filter](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-similarity-search-distance.png)

6. Adjust the **Distance** filter slider to change the similarity search results.

### Embedding View

<Info>
  You must calculate metrics and embeddings before you can view embedding plots.
</Info>

Encord incorporates embedding plots — a two-dimensional visualization technique employed to represent intricate, high-dimensional data in a more comprehensible and visually coherent manner. This technique reduces data dimensionality while preserving the inherent structure and patterns within the original data.

The embedding plot aids in identifying interesting/noteworthy clusters, inspecting outliers, and excluding unwanted samples.

**Use Custom Embedding Plots**

![Vibrant 2D data embedding plot highlighting data patterns and clusters](https://storage.googleapis.com/docs-media.encord.com/static/img/Index/index-custom-embed-scatter-004.png)

Notice how images are clustered around certain regions. By defining a rectangular area on the plot, users can quickly isolate and analyze data points within that defined region. This approach facilitates the exploration of commonalities among these samples.

Hover over clusters or individual data points on the plot to visually check frames.

Upon selecting a region, the content within the *Explorer* page adjusts accordingly. Various actions can be executed with the chosen group:

* Use [Collections](/platform-documentation/Curate/curation-basics#collections) to tag and group images.
* Establish subsets similar to these and then conduct comparisons.


# Use Cases
Source: https://docs.encord.com/platform-documentation/Validation/validation-use-cases



## Data Cleansing/Curation

<div>
  <iframe />
</div>

Alex, a DataOps manager at **self-dr-AI-ving**, faces challenges in managing and curating data for self-driving cars. Alex's team struggles with scattered data, overwhelming amounts of data, unclear workflows, and an inefficient data curation processes. Alex is currently a big user of Encord Annotate, but would like to provide better datasets for annotation.

1. **Initial setup**: Alex gathers a large number of images and gets them imported into Active. Alex then logs into Encord and navigates to Active (freemium).

2. **First collection**: Alex opens the Project and after searching, sorting, and filtering the data, selects the images and clicks **Add to a Collection** and then clicks **New Collection**. Alex names the Collection **RoadSigns** as the Collection is designed for annotating road signs for the team.

3. **Data curation**: Alex then further bulk-finds traffic sign images using the embeddings and similarity search. Alex then clicks **Add to a Collection** and then clicks **Existing Collection** and adds them images to the **RoadSigns** Collection in a matter of clicks.

4. **Labeling workflow**: Thinking about different use-cases (for example, "Labeling" and "Data quality") Alex assigns good quality road signs for labeling, and bad quality road signs for "Data quality" and future "Deletion". In the future Alex might use "Active learning" to prioritize the data for labeling.

5. **Sent to Annotate:** Alex goes to the *Collections* page, selects the *Roadsigns* Collection and clicks **Create Dataset**. Active creates the dataset and [a new Project in Annotate](/platform-documentation/GettingStarted/gettingstarted-create-project). Alex then configures the workflow, annotators, and reviewers for the Project in Annotate.

6. **Review and insights**: At the end of the week, Alex reviews the *RoadSigns* Project in Annotate. The dataset has been annotated. Alex goes to Active, clicks the **More** button on the Project then clicks **Sync Project Data**. Alex then clicks the Project, clicks *Analytics* and then *Model Predictions* where Alex gains insights into:

   * Number of labels per image
   * Quality of annotations
   * Distribution of annotations across metric

The process is seamless and fast, and Alex can focus on more strategic tasks while her team enjoys a much-improved, streamlined data curation workflow.

## Label Correction/Validation

Chris, a Machine Learning Engineer at a micro-mobility startup, has been working with Encord Annotate. His team is dealing with a large set of scooter images that need accurate labeling for obstacle detection. After an initial round of annotations, Chris notices that some labels are incorrect or ambiguous. This has a significant impact on the performance of the ML model.

1. **Access Collections:** Chris logs into Encord Active. Chris opens the Scooters project that was imported from Annotate. Chris goes to the *Collections*  page for the project. Chris browses the existing Collections to see if he should create a new Collection or add to an existing Collection.

2. **Data exploration:** Chris searches, sorts, and filters the previously annotated scooter images and identifies those that need re-labeling.

3. **Create re-labeling Collection:** Chris selects the images and clicks **Add to a Collection**. Chris then clicks **New Collection** and names the Collection **Re-label - Scooters**.

4. **Initiate re-labeling:** With the Collection ready, Chris returns to the *Collections* page, selects the **Re-label - Scooters** Collections and clicks **Create Dataset**. The Collection is sent to Annotate.

5. **Assigning in Annotate:** In Annotate, Chris assigns re-labeling tasks to specific annotators. Annotators then complete their relabeling tasks.

6. **Quality check in Active:** After the re-labeling tasks are completed, Chris clicks **Sync Project Data**. The updated labels then sync back to the Project. Chris reviews the changes, confirms the label quality, and plans for model re-training.

The "Collections" feature has simplified the task of identifying and re-labeling inaccurate or ambiguous data, streamlining the entire data annotation and quality control process for Chris and his team.

## Model/Prediction Evaluation

Dana is a Machine Learning Engineer at a robotics company. Her team wants to improve the performance of their machine learning model used by their robots. She has ground truth labels created by her team and predictions from her model.

1. **Import ground truth labels and predictions:** Dana uses Encord's SDK to import ground truth labels and model predictions into an Encord Annotate Project. After the import, Dana imports the Annotate Project into Active.

2. **Prepare for Evaluation:** Dana "imports" the predictions for Active. Active then performs comparison and optimization calculations between predictions and ground truth labels.

3. **Assess Model Evaluation Analytics:** Dana navigates to the **Analytics View** page and creates several charts to compare her ground truth labels against the model predictions. Dana also navigates to the **Model Evaluation** page and also compares model performance against the ground truth labels. Dana is able to identify a number of areas where her model's performance can improve. For example, using the Model Evaluation charts, Dana discovers that her model has poor performance on dark and low contrast images and videos.

4. **Curate, Relabel, and Retrain:** Dana imports a number of images and videos with dark and low contrast characteristics to Index. She creates a Collection and then a Dataset of these images and videos. Dana then adds the Dataset to her Annotate Project and her team creates new ground truth labels to train the model. Dana exports the labels and trains her model using the new labels.

5. **Import and Evaluate:** Dana repeats the import and evaluation steps with the latest predictions.

6. **Reassess Model Performance:** Dana navigates to the **Model Evaluation** page and creates several charts to compare her ground truth labels against the latest model predictions and the previous model performance. Dana can then continue the cycle until her model reaches the performance she needs.


# 2023
Source: https://docs.encord.com/release-notes/releasenotes-2023

Product Updates and Announcements 2023

<Update label="December 01">
  * [**Threshold Brush Improvements**](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#thresholding): The threshold brush feature for Bitmasks has been upgraded to provide more flexibility when choosing a threshold for your label.  RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) thresholds can be applied, allowing you to target specific color ranges with ease. You can also [preview your work](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#thresholding) in transparent and inverted modes in addition to B/W (black and white).

  * [**Bitmask Lock**](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#bitmask-overlap-management): You can now control how Bitmask labels overlap, ensuring that once a label is created, subsequent Bitmasks do not cover it.

  * **LLM Automated Labeling**: Integration with a Vision-Language Model (VLM) tool enables automatic application of classification labels. All you have to do is define a range of frames for labels to be applied, and the VLM takes care of the rest - prompts are automatically generated based on your ontology. For access and more information, please contact [support@encord.com](mailto:support@encord.com).

  * [**Advanced Editor Timeline**](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#editor-timeline): The new Editor Timeline simplifies your interaction with instances and objects. It now allows you to select and reposition objects and instances. Additionally, you can combine multiple instances into a single instance directly using the timeline. For access and more information, please contact [support@encord.com](mailto:support@encord.com).

  * [**Task Priorities**](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-priority): We have introduced a priority system for tasks. Each task is assigned a priority value ranging from 0 to 100, ensuring that the most impactful tasks get the attention they deserve.

  * **DICOM Decoder**: We introduced a new DICOM decoder to greatly enhance the handling of DICOM files across various browsers. This advancement offers improved performance, and extensive support for a wide range of imaging formats, eliminating any need to pre-process your DICOM files. For access and more information, please contact [support@encord.com](mailto:support@encord.com).
</Update>

<Update label="November 15">
  * [**Edit Review**](/platform-documentation/Annotate/annotate-label-editor#edit-labels-during-review): Reviewers can now edit annotations directly instead of outright rejecting them. This enhances the efficiency of the review process by allowing immediate corrections, thereby saving time.
  * [**Label versioning**](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#save-label-version): Saving label versions enables the creation of snapshots for specific subsets of labels, which can be exported or referenced in the future. This allows you to track changes over time, enhancing quality control and offering improved oversight of annotators' work.
  * **Label Export**: All label actions are now taken in the *Labels* tab where you can conveniently [export the latest state of your labels](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels) as well as previously snapshotted label versions.
  * **Improved Composer UI**: Enhancements to the Workflow Composer include a smoother experience in building Workflows and Templates. Components are now connected with colored, non-overlapping lines for clearer visualization of Workflows - making the composer more user friendly by reducing confusion and the possibility of errors while setting up a Workflow.

  ***

  * [**Pixelated Scaling**](/platform-documentation/Annotate/annotate-label-editor#pixelated-scaling): The *Pixelated scaling* feature prevents browsers from automatically smoothing edges when zooming into a frame or image, helping annotators create precise and pixel-perfect annotations.
  * [**Bitmask Updates**](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#thresholding): The improved *Threshold brush* tool now supports RGB and HSV thresholds. A new feature highlights pixels above the threshold in white for clearer previews - improving annotation accuracy, especially for darker images.
  * [**SAM Updates**](/platform-documentation/Annotate/automated-labeling/annotate-sam): SAM (Segment Anything Model) is now available for the Bitmask annotation type, providing a convenient way of applying bitmask annotations.
  * \[**Improved Performance**]: Enhanced Label Editor performance now accommodates larger volumes of labels. For access and more information, please contact [support@encord.com](mailto:support@encord.com).

  ***

  * **AI Help Bot**: The AI Help Bot is fully integrated into the Encord platform, offering immediate assistance for your queries without the need to leave the platform. We even use it internally when we have questions about our platform.
  * [**Encord Labs**](/platform-documentation/Annotate/annotate-settings-general#encord-labs): Encord Labs offers select customers advanced and Beta features. For access and more information, please contact [support@encord.com](mailto:support@encord.com).
</Update>

<Update label="October 13">
  * **[Annotating on Different Tiles](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#switch-annotation-series)**: Seamlessly switch annotation focus while preserving tiling layout.

  * **DICOM Zooming**: Upgrades to the DICOM label editor provide a smoother experience when zooming.

  ***

  * [**Strict Review**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#strict-review): The new *Strict review* setting prevents tasks from auto-submit when labels are processed. See our documentation for details on implementation, as well as suggested use-cases.
  * [**Change Review Judgment**](/platform-documentation/Annotate/annotate-label-editor#changing-judgement): Reviewers can now revert their actions to make adjustments to one or more label instance reviews.

  ***

  * **Session and Data Tab Alignment**: Only tasks listed in the [*Data tab*](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects) are displayed in the Label Editor, even when the list has been filtered.

  ***

  * **New notifications UI**: Notifications appear automatically when performing actions such as exporting labels.

  * **Encord Active**: Performance and stability improvements.
</Update>

<Update label="September 28">
  * **Benchmark QA**: Benchmark QA and training projects now support DICOM files.
  * **DICOM Loading**: Upgrades in DICOM loading performance for a smoother experience within the label editor.

  ***

  * [**Keypoint Annotations**](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#objects): You can now use keypoint annotation classes in both Benchmark QA and Annotator Training projects, expanding your annotation and annotator training possibilities.
  * [Bitmasks](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#updating-bitmask-labels): Performance and stability enhancements for working with bitmask annotations and the brush tool!

  ***

  * [**SAM**](/platform-documentation/Annotate/automated-labeling/annotate-sam): SAM performance improvements.
  * **Performance Dashboard**: Experience significant speed improvements when navigating the Performance Dashboard's details page.
</Update>

<Update label="September 13">
  * \[**NEW**] [**Queue Tab**](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-queue-and-workflow): Admins and Team Managers can now manage tasks within Workflow Projects using the new *Queue* tab. Use the *Queue* to get a comprehensive overview of all stages and for easy task assignment, initiation, and release.
  * **UI/UX Upgrade**: Enhanced [Workflow Composer](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#workflow-composer-components) simplifies the workflow creation process.

  ***

  * [**Angle Display**](/platform-documentation/Annotate/annotate-label-editor#measure-polygon-and-polyline-angles): Polygon and polyline angles are now visible in the label editor
  * [**Polygon Brush Tool**](/platform-documentation/Annotate/annotate-label-editor#polygon-brush-tool): Usability improvements.
  * **Zoom Behavior**: Optimized zoom behavior for DICOM.

  ***

  * **DICOM File Validation**: Enhanced error reporting for DICOM files uploaded via the web-app. Including encoding diagnostics and identification of other upload issues.
  * **Import Logs**: Clearer messaging for dataset imports using local data, including encoding diagnostics and identification of other upload issue(s).

  ***

  * **Performance**: Speed and performance improvements across the Encord platform.
  * **SDK**: Refined label upload functionalities.
</Update>


# 2024
Source: https://docs.encord.com/release-notes/releasenotes-2024

Product Updates and Announcements 2024

<Update label="December 19">
  * **Text & HTML in Index & Annotate**: Text files in various formats, including raw and single-extension HTML, are now [supported in Index](/platform-documentation/Curate/index-text-files) and [Annotate](/platform-documentation/Annotate/annotate-label-editor/annotate-text-html). A new Ontology class for labeling text regions has been introduced, enhancing annotation capabilities and enabling advanced text labeling workflows.

  * **Audio Annotation**: You can now label specific audio regions using a new Ontology class, enabling more complex workflows such as [audio transcription](/platform-documentation/Annotate/annotate-label-editor/annotate-audio#audio-transcription) using text attributes. This aligns audio annotations with other modalities, making workflows smoother and more cohesive.

  * **Custom Agents**: Custom Agent JSON payloads now use the `application/json` content type in their headers, enhancing compatibility with a wider range of server configurations. This update ensures smoother integration and reduces potential issues when handling JSON payloads in your workflows.

  * **Active Project Import**: Customers can now import and sync Projects into Active using the Encord SDK. This marks a significant step toward fully SDK-driven workflows.

  * **Filter Presets**: Filter presets in Encord Active now have SDK support, simplifying SDK-driven workflows across Active and other Encord products.

  * **Encord US Deployment**: The [US-specific Encord App](https://app.us.encord.com/) is now live! This deployment reduces app latency for US-based customers.
</Update>

<Update label="November 25">
  * **Object Primitives**: Object Primitives (Skeletons) have been redesigned for enhanced usability and efficiency. You can now place each skeleton point sequentially, eliminating the need to manually drag and adjust each point. This streamlines the process, making skeleton creation and adjustments faster and more intuitive. Additionally, the UI for marking points as *invisible* or *occluded* has been improved, making it easier to use and more discoverable. This enhancement ensures a smoother experience when labeling complex data.

  * **SDK Task Submission**: The SDK now offers enhanced support for task management. You can [assign](/sdk-documentation/projects-sdk/sdk-workflows-stages#assign-a-user-to-tasks-in-a-stage) and [submit](/sdk-documentation/projects-sdk/sdk-workflows-stages#submit-tasks-as-another-user-in-a-stage) annotation or review tasks on behalf of other users, provided you have the required permissions.

  * **Audio Classification Support in SDK**:Audio workflows are now [supported in the SDK](/sdk-documentation/sdk-labels/sdk-audio-classifications)! You can programmatically view, import, and export classifications for audio files.

  * **Active Collections SDK Access**: You can now work with [Collections in Active using the SDK](/sdk-documentation/api-active/sdk-active-collections). Programmatically create, update (add/remove frames and labels), and list Collections to streamline your SDK workflows.
</Update>

<Update label="November 14">
  * **Bulk Edit & Delete Labels in Active**: Quickly make bulk changes to object and classification labels across Active and Annotate using Label Collections (distinct from Data Collections). This feature unlocks more efficient workflows for label QA and editing.

  * **Custom Embeddings in Active**: Active now supports custom embeddings with dimensions ranging from 1 to 2000, empowering users to integrate and leverage their own embeddings seamlessly.

  * **Index SDK Code Snippets**: Access SDK code snippets for Index Collections and Presets actions directly in-platform. This feature offers precise, context-specific guidance, simplifying SDK implementation for user-specific needs.
</Update>

<Update label="November 04">
  * **Pre-Annotate before Consensus**: You can now add other stages before a consensus stage in your Workflow. This can be used to, for example, allow pre-labels to appear within consensus tasks and provide annotators with a consistent starting point.

  * **Upload labels to Consensus stage**: You can now upload pre-annotation labels as separate subtasks within a consensus stage, enabling streamlined comparisons. This feature is ideal for scenarios where multiple users' labels are compared at the consensus stage, or when different model outputs are compared within a consensus workflow. This allows you to, for example, assign different pre-labels to annotators within a consensus task, or to upload and compare various model outputs as part of the consensus review process.

  * **Service Accounts**: Customers can now create [service accounts](/platform-documentation/General/general-access-keys#using-service-accounts) for programmatic platform access directly within their organization settings. Each organization is allotted one service account by default. If additional accounts are required, please reach out to your account manager.

  * **Unlimited URL Length for Source Media**: The previous 300-character limit for video URLs (e.g., from AWS, GCP) has been removed, allowing unlimited URL length. This update supports even the longest pre-signed URLs, enhancing compatibility and ease of access for extended links.

  * **Active & Index Updates**: Filters and workflows for [adding files to collections](/platform-documentation/Curate/curation-basics#collections) in Active and Index have been redesigned for improved efficiency. Filters are now more compact, always visible, and workflows benefit from hotkey support, streamlining task handling and collection management.

  * **Multi-factor Authentication Enhancement**: Users can now choose their preferred method for multi-factor authentication, selecting either an authenticator app for a Time-based one-time password (TOTP), or SMS.
</Update>

<Update label="October 15">
  * **Project Completion Percentage Indicator**: We've introduced a Project completion percentage indicator, which shows the percentage of tasks that have reached the "Complete" stage. This feature allows Project admins to quickly assess the status and progress of their Projects at a glance.

  * **Bulk Task Handling**: Tasks within a single layout group, in custom editor layouts, now progress through the Workflow together. This means tasks are submitted, approved, rejected, skipped, or reopened as a unified group, ensuring efficient handling of related tasks. This enhancement is especially beneficial for RLHF workflows.

  * **Grouping Labels by Class**: You can now group labels by class within single images and within a single frame view using the [*Group by class* button in the Label Editor](/platform-documentation/Annotate/annotate-label-editor#instances-and-frame-labels), streamlining the review and editing process for complex Ontologies.

  * **NIfTI Upload using SDK**: The SDK now supports uploading NIfTI files directly from a local machine, making it easier to manage medical imaging and other NIfTI-based datasets.

  * **Multiple Branches per Data Unit**: The SDK now allows the creation of multiple [label row branches per data unit](/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud#prediction-branches) within a Project, providing greater flexibility for managing complex annotation tasks. This supports the prediction upload workflow for Encord Active.

  * **[Encord Active: Prediction Upload Workflow](/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud)**:
    * The label branch functionality can now be used to support prediction comparisons to ground-truth labels in Active.
    * When importing or syncing a Project to Encord Active, all label branches are automatically imported, including any label branches that include predictions.
    * In Encord Active, you can specify which prediction set to analyze, offering more control and flexibility when evaluating prediction results.
</Update>

<Update label="September 20">
  * **Activity center**: We are pleased to introduce the new [Activity Center](/platform-documentation/General/general-workspace-settings#activity-center), which monitors your Workspace's activity. The activity center provides a detailed view of completed jobs and identifies the users who performed them, giving you greater insight into your team's operations.

  * **Review Queue**: The review queue now has a 'Last Actioned' column, allowing you to easily view and filter tasks by the user who last submitted them. This enhancement improves task assignment and management by providing better visibility into who created specific labels, making it easier to allocate tasks based on team activity.
</Update>

<Update label="September 18">
  * **Custom Analytic Dashboards for Active and Index**: You can now create custom analytic dashboards in Active and Index. You can add Distribution and Correlation cards with a number of display criteria.
    * Active
    * Index

  * **Collections and Preset Filter SDK**: [Index Collections and Preset Filters](/sdk-documentation/index-sdk/sdk-collections) now both support programmatic use with Encord's SDK.

  * **SDK Reference Updates**:
    * [UserClient](/sdk-documentation/sdk-references/user_client#get-collection)
    * [Collection](/sdk-documentation/sdk-references/collection)
    * [Preset Filter](/sdk-documentation/sdk-references/filter_preset)
    * [Inaccessible storage items](/sdk-documentation/sdk-references/orm.storage#storageiteminaccessible-objects)

  * **Similarity Search Filter**: You can specify the "distance" between similar items using the Distance filter on similarity searches.

  * **Embedding Plots with Custom Embeddings**: After "upgrading" your top-level Folder, you can view 2D embedding plots in Index.
</Update>

<Update label="August 20">
  * **Introducing Workflow Agents**: Fully customizable components tailored to your needs, seamlessly integrated into your annotation and quality control workflows. Ideal for pre-labeling, automated reviews, model-in-the-loop functionalities, integrating foundation models, and other scalable automated tasks!

  * **Agents**: Our new *Agents* interface in the Encord platform provides a centralized hub for [Agents](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview), and Models.

  * **Annotation Instructions**: The [annotation instructions drawer](/platform-documentation/Annotate/annotate-label-editor#view-annotator-instructions) in the Label Editor now allows annotators to view instructions while performing annotations simultaneously, increasing the efficiency and accuracy of annotators.

  * **Datasets**: For customers with **Sources** enabled, [Datasets](/platform-documentation/Annotate/annotate-datasets/annotate-datasets) are now part of *Annotate*, highlighting their relevance and usage within Projects in both Annotate and Active.
</Update>

<Update label="August 05">
  * **Expanded Audio Format Support**: We expanded [audio format support](/platform-documentation/Curate/index-audio#index-audio-support) in Index to include `eac3` and `m4a`.

  * **[SAM 2](/platform-documentation/Annotate/automated-labeling/annotate-sam#sam-2-beta)**: SAM 2 has been available in Encord since July 31st, offering enhanced processing capabilities. To enable SAM 2, access Encord Labs. For access to Encord Labs, contact support at [support@encord.com](mailto:support@encord.com).

  * **COCO Label Imports**: You can now effortlessly [import labels / annotations in the COCO format](/sdk-documentation/sdk-labels/sdk-import-coco-labels) using the Encord SDK.
</Update>

<Update label="July 26">
  * **Audio file support for Index:** Index now supports the [curation and organization of your audio data](/platform-documentation/Curate/index-audio).
  * **Custom embeddings in Index:** Index now supports [custom embeddings](/platform-documentation/Curate/custom-embeddings). You can now use your own embeddings to enhance the accuracy of data curation and organization.
  * **Re-index Index files:** Re-index when you change indexing instructions such as which frames you need indexed. You do not need to re-index when changing custom metadata. Refer to our [documentation](/platform-documentation/Curate/curation-basics#re-index) for more information.

  ***

  * **Label Editor Customization**: Configure custom label editor layouts that suit your needs for Projects. Custom label editor layouts are set using JSON files that are uploaded in the Project settings. Check out our [documentation for more information](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#custom-editor-layout).

  * **Encord provides boilerplate Workflow templates**:

    * **Standard workflow**: A Workflow template with a single Annotate and a single Review block.
    * **Double review workflow**: A Workflow template that builds on the \*\*Standard workflow \*\* template with a routing block and a second Review block.
    * **Consensus workflow**: A Consensus Workflow template with a single Consensus (Review & Refine) block.
    * **Tie-breaker Consensus workflow:** A Consensus Workflow template with two Consensus (Determine Consensus) blocks.

    All Workflow templates are available during Project creation.

  * **Consensus - General Release**: Consensus workflows are no longer in BETA. Consensus workflows have been battle-tested and are no longer in BETA. If you haven't already, check out how Consensus Workflows can vastly improve your annotation workstream. Refer to our documentation for more information on [Consensus Workflows](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus). Consensus workflows now support `get_label_reviews` using the SDK. This method returns Review tasks. Those tasks can then be approved/reopened/rejected.
</Update>

<Update label="July 05">
  * **Improved Search UX**: We've enhanced the search user experience within the **Files & Folders** section by allowing you to explicitly choose the scope of your search. You can now select whether you want to search within all folders or only specific folders.

  * **Global Search**: The global search is now conveniently located in the left-hand side navigation menu.

  * **New Support Widget**: We've introduced a new customer support widget with a fresh design that significantly enhances your overall user experience.

  ***

  * **Workflow TaskStatus**: We have introduced a “status” field for Workflow tasks, indicating the current status of the task, such as `NEW`, `ASSIGNED`, and `RELEASED`. You can now filter tasks using the “status” field in the `workflow_stage.get_tasks()` call. To read more from the SDK reference material, go [here](/sdk-documentation/projects-sdk/sdk-workflows-stages) and to learn how to filter tasks by status go [here](/sdk-documentation/projects-sdk/sdk-workflows-stages#filter-tasks-by-status).

  * **Automatic Task Assignment**: Tasks moved using Encord's SDK are now automatically assigned to Tasks to the person executing the `task.submit()`, streamlining task management and assignment processes.
</Update>

<Update label="June 21">
  * **NIfTI Support**: We've introduced native [support for Neuroimaging Informatics Technology Initiative](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom)(NIfTI) files in our Label Editor, expanding our capabilities for neuroimaging data.

  * **Auto-segmentation tracking for DICOM**: [Auto-segmentation tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam#sam-2-tracking) is now available for DICOM series, streamlining your workflow when labeling DICOM series. Use the 'Shift + T' keyboard shortcut to track an object across multiple slices.

  * **Label Copy/Paste Enhancement**: [Copying and pasting](/platform-documentation/Annotate/annotate-label-editor#copy-and-paste-labels-and-instances) objects in the Label Editor now preserves the rotation of rotating bounding boxes, ensuring consistency when duplicating elements.

  * **Improved UX for Index**: We've enhanced the user experience of the **Sources** section by applying ascending order sorting by default for files in Folders. Additionally, we've added sorting options like 'by name' and 'last modified' for better file management.

  **Cloud Integration Support**: We've added more [cloud storage integration](/platform-documentation/General/annotate-data-integrations) options including Wasabi, MinIO, and Oracle's cloud.
</Update>

<Update label="June 12">
  * **Auto-Segmentation Tracking**: We've introduced [auto-segmentation tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam#sam-2-tracking) for both bounding boxes and rotatable bounding boxes. This enhancement is designed to speed up your workflow when tracking objects in videos using these shapes.

  * **Task Queue**: You can [filter tasks](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#filter) in the [queue](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-queue-and-workflow) tab by all current exposed statuses, including `NEW`, `SKIPPED`, and `REOPENED`. This feature provides greater flexibility, allowing users to precisely manage and prioritize tasks based on their specific status.

  * **Configure Workflow Stages**:
    * You can now configure ANNOTATE and REVIEW blocks to allow or prevent users from annotating or reviewing tasks they have previously worked on. Use the [Advanced settings: Allow task reassessment](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus-review-project#advanced---allow-task-reassignment) feature in ANNOTATE and REVIEW blocks to configure the setting.
    * Consensus ANNOTATE and REVIEW blocks no longer require you to assign users to those blocks. This means Consensus blocks now follow the same behavior as non-Consensus blocks.

  * **Quick Toolbar**: Each tile in the DICOM label editor now includes its own [quick toolbar](/platform-documentation/Annotate/annotate-label-editor#quick-toolbar).
</Update>

<Update label="May 24">
  * **Admin Access Improvements**: Workspace admins can now join all [Projects](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#join-projects-in-your-workspace) , [Datasets](/platform-documentation/Annotate/annotate-datasets/annotate-datasets#joining-datasets-in-your-workspace) , [Ontologies](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#view-and-join-ontologies-in-your-workspace), and [Integrations](/platform-documentation/General/annotate-data-integrations#view-and-join-integrations-in-your-workspace) directly from their respective sections, rather than through the Workspace page.

  * **Review Settings**: We've added *Advanced settings* to the Review node, allowing you to adjust review settings like [strict review](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#strict-review).

  * **Card/Tile Redesign in Active**: While in Grid view, you can choose details (metrics, custom metadata, Collection, title) to appear on each card/tile.   This redesign enhances the data visibility for your cards/tiles.

  * **Predictions and Labels Displayed Together**: We've improved the Predictions page by displaying ground-truth labels (labels from Annotate) with your prediction labels in Encord Active.

  * **Prediction Confidence Slider**: Introducing the `Predictions Min Confidence Threshold` slider. The slider allows you to filter predictions based on their confidence level to help when optimizing your model performance.

  * **Model Evaluation Enhancements**: We have improved our model evaluation algorithms to provide more accurate model assessments.

  * **Infinite Paging**: We've added infinite pagination to the **Sources** , allowing for highly performant navigation and access to all your files without needing to click through multiple pages.

  * **SDK Workflow Support**: Workflow support in the SDK for both Consensus and non-Consensus Projects. You can assign, approve, reject, submit, and release tasks in your Workflow Projects programmatically. Additionally, you can query tasks by stage in a performant manner. Refer to our SDK documentation for more information.
</Update>

<Update label="May 17">
  * **Cloud Integrations In Workspaces**: [Cloud integrations are now visible and manageable](/platform-documentation/General/general-workspace-settings#view-and-join-integrations-in-your-workspace) within the Workspace interface. This update provides enhanced control and visibility over integration access.

  * **Index**: We've streamlined the file upload process by automatically selecting newly created folders as the target for uploads. Additionally, we've made file tutorials easy to dismiss, hidden legacy "Mirrored" Datasets from the file browser, and exposed tutorials in the right-hand side panel of **Sources**.

  **DICOM Multi-Series**: We've added multi-series upload support for DICOM files in the UI, allowing you to add files belonging to multiple DICOM series simultaneously. This enhancement improves the efficiency of DICOM file uploads and reduces errors when files from multiple series are included.

  * **Review and refine** is now an [option inside the Consensus REVIEW block](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus-review-project). You can now choose between modes for the Consensus block: **Refine and review** and **Determine consensus**. **Review and refine** is the default mode.

  * **Workflow composer Enhancement**: We have improved the Workflow composer with clearer prompts and queues to prevent losing progress while assembling templates.
</Update>

<Update label="May 10">
  * **[Review and Refine Consensus Labels](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus-review-project#review-and-refine-consensus-labels)**: You asked and we delivered! Reviewers can now select the best labels from all annotators, using the REVIEW and REFINE block. Connecting the *No consensus* output of a CONSENSUS block to the input of a REVIEW block creates a REVIEW and REFINE block. From the REVIEW and REFINE block, reviewers can select the best labels from any annotator, in the Consensus block, for any object or frame.

  * **MFA**: You can now require all members in your Workspaces to turn [on multi-factor authentication](/platform-documentation/Annotate/annotate-label-editor#comments). Contact [support@encord.com](mailto:support@encord.com) to get started with MFA!

  * **Cloud Integration Access**: The new interface offers enhanced control and visibility over [user access for each integration](/platform-documentation/General/annotate-data-integrations#add-and-remove-users). You can now easily add and remove users from integrations, as well as seamlessly view which users are assigned to each cloud integration, ensuring precise management of access permissions.

  * **DICOM X-Axis Support**: X-axis label support is now a reality when labeling DICOM series slices. Additionally, we’ve added the [option for rendering DICOM slices in their original resolution](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#dicom-editor-settings), which is especially beneficial for work requiring high detail. While native resolution can demand more from system performance on longitudinal volumes, it remains the recommended viewing option for Digital Breast Tomosynthesis (DBTs) and other single-slice modalities to ensure the highest quality imaging.

  * **Dynamic Attributes in Consensus**: Dynamic changes incoming! Consensus Projects now feature dynamic attributes in the timeline and the left-hand menu of the Label Editor, enhancing both labeling and reviewing processes.

  * **Comments**: The updated [comments](/platform-documentation/Annotate/annotate-label-editor#comments) interface has been enhanced to remain visible during annotations, allowing you to view and interact with comments without disrupting your workflow. This new design simplifies the process of adding replies and viewing threads, significantly improving usability.

  * **Index**: Action buttons have been introduced in the [Files section](/platform-documentation/Curate/index-files) to enhance visibility and discoverability, streamlining user access to functions from the right-click context menus.
</Update>

<Update label="May 03">
  * **[SDK Data Import](/sdk-documentation/getting-started-sdk/sdk-register-data-aws)**: Troubleshooting file uploads is now straightforward with our new error API. Quickly access file URIs when issues arise during file uploads through the SDK.

  * **[Task Queue](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-queue-and-workflow-annotator-reviewer-admin-team-manager) Improvements**: Enhancements to the task queue now ensure that the order of tasks in the Label Editor accurately reflects the sequence in the *Queue* tab, even when filtering. Additionally, you can better manage your tasks by [organizing the queue](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#sort-by) by priority or task name, with options to sort in either ascending or descending order.

  * **Data Upload**: We've simplified the data upload process in *Index*. Users can now add data directly from the **Sources** section, or by specifying a folder in the Datasets section. This streamlined approach improves usability by eliminating preliminary attachment steps, making it more straightforward and efficient.

  * **Upgrading Mirrored Datasets**: You can now seamlessly upgrade your mirrored Datasets to standard folders and Datasets in just a couple of clicks, enabling you to use your data units across multiple Datasets and organize your files into different folders.

  * **Persistent Auto-Segmentation in Label Editor**: When [auto segmentation](/platform-documentation/Annotate/automated-labeling/annotate-sam) is activated during annotation, remains enabled until it's manually deactivated. This prevents the need for reactivation and provides a seamless annotation experience.

  * **Faster classification workflows**: A [new Label Editor setting](/platform-documentation/Annotate/annotate-label-editor#expand-classifications) enables you to automatically expand classifications. Enhanced hotkey support makes navigating through image classifications lighting fast.
</Update>

<Update label="April 19">
  * [**Strict Review**](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#strict-review): All review mode stages are now Strict review when setting up a new [Workflow](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#workflows). This means all tasks will be stopped for review, even without labels. More information can be found [in our documentation](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#strict-review).

  * [**Task Queue**](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-queue-and-workflow): The order in which tasks appear in the Label Editor now mirrors the order that tasks are listed in the Queue tab for annotators, even when filtering the task list. This functionality will soon be extended to include Review stages.

  * **Index UX Enhancements**: We've implemented several UX enhancements to [Encord Index](/platform-documentation/Curate/index-files). Storage has been renamed to Files, and synced folders are now mirrored folders, making the features more intuitive and accessible.
</Update>

<Update label="April 12, 2024">
  * **[Auto Segmentation Tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam#sam-2-tracking)**: We're thrilled to introduce our groundbreaking auto-segmentation tracking feature - allowing you to effortlessly track bitmask and polygon annotations across a range of video frames. It dynamically adjusts the shape of your labels in response to changes within the video, ensuring consistently high accuracy in your annotations!

  * **[Consensus Workflows](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus-review-project) now support object labels**: Objects are now supported in Consensus workflows. Simultaneously review all annotator submissions in one editor review session.

  * **[Exporting Consensus Labels](/sdk-documentation/sdk-labels/sdk-export#export-all-consensus-labels)**: You can now use the SDK to download labels made by all annotators in a consensus Project.

  * **Study-Level Classifications**: Our latest UI update enhances the Label Editor, allowing you to apply classifications to an entire DICOM series or the whole study directly while viewing individual series. This streamlined functionality improves efficiency and usability, enabling a more intuitive interaction with your data.

  * **[Auto Layouts](/platform-documentation/Annotate/annotate-label-editor/annotate-mammo#auto-layouts)**: We've introduced new settings that enable you to configure auto layouts using standard hanging protocols for mammography files, significantly improving the efficiency of reviewing mammography images. Choose between 2x2 and 4x1 layouts with only a click of a button in the Label Editor settings!

  * **Full SDK Support for Object Primitives**: The SDK now allows direct manipulation of object primitives, simplifying the import into, and export from Encord. This enhancement boosts workflow flexibility and efficiency, facilitating seamless integration and collaboration.

  * **9x Faster Label Download Speed** - We've fine-tuned the label downloading process, which is now up to five times faster, enabling you to download your labels more quickly. This significant speed increase streamlines your workflow, allowing you to focus more on analysis and less on waiting.
</Update>

<Update label="March 22">
  * **Advanced Video Editor Timeline - General Release**: We're excited to announce that our advanced [video editor timeline](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#editor-timeline) features, designed to streamline your workflow and enhance your editing efficiency! Enjoy the convenience of [moving](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#moving-objects-and-instances) and [merging](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#merging-instances-on-the-timeline) instances directly on the editor timeline. You can also quickly see frame objects, and their attributes, just by hovering over them on the timeline.

  * **SDK Label Validation**: You can now confirm the validity of your label structure before saving. This feature helps you identify and correct errors on the spot, preventing any downstream complications. Discover how to leverage the [new parameters](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects) and [error checking techniques](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects#get_validation_errors) in our SDK reference [here](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects)!
</Update>

<Update label="March 15">
  * **Annotator Training Bitmask Support**: Annotator training Projects now support bitmasks, enabling you to effectively train and assess your annotation team on the use of bitmasks for label creation.
</Update>

<Update label="March 07">
  * **Bitmask Enhancements**: You can now combine bitmasks using Label Editor V2, streamlining and improving your bitmask annotation process.

  * **DICOM Import Improvements**: We've improved the import functionality for DICOM series imports to make them faster and more robust when importing very large series. We're also now providing more comprehensive error messages for invalid DICOM series imports.

  * **Enhanced Video Support**: You're now able to annotate your h265 encoded mp4 videos natively in Encord. We've added support for h265 in mp4 containers for Chrome browsers, meaning you no longer need to re-encode your videos before importing them into Encord.
</Update>

<Update label="March 01">
  * [**Editor Settings**](/platform-documentation/Annotate/annotate-label-editor#editor-settings): Searchable Label Editor settings let you customize the Label Editor with speed and with ease. Use the search bar to filter for the names of settings or use a keyword search to bring up related settings! In addition to a search bar, media dimensions can now be seen in the editor settings.

  * [**Bitmask Enhancements**](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#segmentation-masks-bitmasks): Panoptic mode provides an innovative approach to manage the overlap behavior of bitmasks, making it easier to draw multiple bitmask labels close to each other.
</Update>

<Update label="February 22">
  * **Bitmask Performance**: We've enhanced the performance of [Bitmasks](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#segmentation-masks-bitmasks) in the Label Editor, allowing you to create hundreds of Bitmask labels faster than ever before. ⚡

  * [**DICOM HJT2K Support**](https://encord.com/blog/htj2k-support-for-dicom-files-encord/): Our platform now supports HTJ2K (High Throughput JPEG 2000), which enhances loading and rendering times. Ultimately this reduces the time required to annotate DICOM files.

  * **Downloading Models**: Model weights can now be downloaded from Encord, allowing you to use your micro-models outside our platform.
</Update>

<Update label="February 02">
  * **Label Editor Interface Improvements**: The new [editor menu](/platform-documentation/Annotate/annotate-label-editor#editor-menu) in the top left corner of the Label Editor consolidates frequently used editor actions into a single, accessible location and reduces the chance of unintended clicks forcing you out of the Label Editor.

  * **Further Workflows Performance Enhancements**: Large [Workflow Projects](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects) have received a significant upgrade - actions such as loading tasks, and submitting annotations are now up to 5x faster! 🏎️

  * **DICOM MPR And Bitmask Annotation Enhancements**: You can now annotate Bitmask labels in [DICOM MPR views](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#labeling-reconstructed-views). Additionally, use the [cylinder brush tool](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#3d-cylinder-brush) and control slice thickness to annotate in multiple slices at once from any DICOM view in a powerful step towards 3D labeling capability.

  * [**Custom DICOM Overlay Support**](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#custom-overlay): Tailor the display of metadata in the Label Editor to conveniently access the information you need while annotating.
</Update>

<Update label="January 23">
  * **SDK Label Exports**: Our latest performance enhancements allow you to [export labels from Encord using the SDK](/sdk-documentation/sdk-labels/sdk-export) up to 20 times faster than before!

  * **[Skip Annotation Tasks](/platform-documentation/Annotate/annotate-label-editor#skip-a-task)** : Annotators can skip tasks when, for example, the file is blurred, or if they suspect the task was erroneously added. Comments are added to skipped tasks so other users can see the reason the task was skipped.

  * **Quickstart Help**: New annotators and reviewers now have access to tailored tutorial videos in the Label Editor, designed to ramp up their introduction to Encord. These videos are available anytime for a convenient refresher, helping users recall essential information whenever needed!
</Update>

<Update label="January 12">
  * **[DICOM Metadata Viewer](/platform-documentation/Annotate/annotate-label-editor/annotate-dicom#metadata)**: Improved ability to accurately render private tags.

  * **Workflow Composer**: We've polished our [Workflow composer](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#workflows) by improving the appearance of nodes and connections. This provides you with a more visually appealing and user-friendly experience when creating and editing Workflows.

  * **In-App Release Announcements**: Release announcements now appear in our application! Now you can stay up to date with the latest developments in Encord.
</Update>

<Update label="January 05">
  * **[Streamlined Project Creation](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#creating-annotation-projects)**: Create projects faster and more intuitively on a single screen. Select workflows, use templates, and manage ontologies and datasets, all in one place! 🚀
  * **[Highlight Data Integrations](/platform-documentation/General/annotate-data-integrations)**: Data integrations now appear in the main navigation, providing quick access and highlighting their importance in Encord.
  * **Improved Homepage**: We've improved our landing page to guide you to the most important parts of the Encord platform as quickly as possible.

  ***

  * **Improved Review Workflow**: Tasks rejected in a [*Review* stage](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#review) can now be moved to additional *Review* stages to serve as a tie-breaker. For access, reach out to [support@encord.com](mailto:support@encord.com).
  * **Performance Enhancements**: Significant performance improvements ensure faster loading and processing of annotation and review tasks in Workflow projects, enhancing overall efficiency.

  ***

  * **[Flexible Import](/sdk-documentation/sdk-references/user_client#create_project_from_cvat) and [Polyline Support for CVAT](/sdk-documentation/projects-sdk/sdk-import-cvat#comparing-annotation-shapes-cvat-vs-encord)**: CVAT polylines can now also be imported into Encord, ensuring your CVAT polyline labels remain unchanged when you switch to our platform! Adapt your CVAT imports by mapping image file names with names found in the annotation XML, in cases when they don't match exactly.
</Update>


# 2025
Source: https://docs.encord.com/release-notes/releasenotes-2025

Product Updates and Announcements 2025

<Update label="December 5">
  * **[CoreWeave Integration](/platform-documentation/General/annotate-data-integrations/annotate-coreweave-integration)**: You can now integrate with CoreWeave Cloud Storage to seamlessly access your data directly within Encord.
</Update>

<Update label="November 26">
  * **Task Specific Label Export**: You can now [export labels](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels) for specific tasks by selecting those tasks before exporting.
</Update>

<Update label="November 21">
  * **[SAM 3 (Early Access)](/platform-documentation/Annotate/automated-labeling/annotate-sam)**: We’ve integrated SAM 3 into the platform, bringing faster and more flexible automated labeling. SAM 3 allows you to label all object instances simultaneously using a text prompt, or one click action from a class name. SAM 3 is currently in Early Access. The user experience is still being refined and may change as improvements are introduced. Contact us at [support@encord.com](mailto:support@encord.com) to gain access to SAM 3.
</Update>

<Update label="November 13">
  * **Hide Unassigned Tasks**: When enabled for an Annotate or Review stage, users with the *Annotator*, *Reviewer*, or *Annotator & Reviewer* roles can only view tasks assigned to them. Admins and Team Managers can see all tasks, including unassigned ones.

  * **General improvements to video modality**:
    * File name copying is now more intuitive on the canvas.
    * “Go to frame” navigation is easier to find and instantly accessible.
    * Additional play and jump functions have been moved to the context menu, improving hotkey discoverability.
    * Frame skip interval and timestamp/frame display settings are now hidden under a dedicated toggle, with clearer hotkey guidance.
    * The loading bar has been redesigned for a more intuitive, modern video player experience.
    * New hotkeys added for playback speed — use the <kbd>up</kbd> and <kbd>down</kbd> arrow keys to adjust.
</Update>

<Update label="October 22">
  * **[Ontology Archiving](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#archive-and-delete-entries) & Safe Editing**: When an Ontology is attached to a project, items are now archived instead of deleted, and you can see which edits are safe or destructive. This prevents broken labels and keeps your Ontology clean and up to date.

  * **[Ontology Versioning](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#view-edit-history)**: Ontology changes are now tracked automatically with a full version history showing who made each change, when, and why.

  * **[Data Groups](/platform-documentation/Curate/data-groups/index-data-groups)**: You can now batch files into Data Groups directly in the Encord UI, using the default carousel or grid layout. Custom layouts can be created through the SDK.
</Update>

<Update label="October 9">
  * **Backwards Tracking**: [SAM 2 Object Tracking](/platform-documentation/Annotate/automated-labeling/annotate-sam) now supports tracking backwards through videos, so you can start labeling from any frame—not just the first appearance of an object. This makes it easier to track objects that become relevant later or are clearer in later frames.
</Update>

<Update label="September 25">
  * **Moving Tasks (SDK)**: The SDK now supports direct Task Move between arbitrary workflow stages, bypassing the previous constraint of sequential stage progression. See the SDK documentation for method and example [here](/sdk-documentation/projects-sdk/sdk-workflows-stages#move-tasks).
</Update>

<Update label="September 18">
  * **Long Audio Files**: You can now pre-generate waveforms offline for audio files, eliminating long delays when opening large tasks. This means faster loading, and more efficient annotator time.

  * **User Invites**: Users invited to your Workspace can now accept invitations from the Home screen of the Encord app.
</Update>

<Update label="August 29">
  * **Removed Labels & Export Tab**: In our on ongoing effort to simplify label export and version management, we removed the Labels & Export tab from Projects. Labels are now exported using the [new export button](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels#recommended), and [label versions are saved](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#save-label-version) in the Settings tab of your Project.

  * **Workflow Templates**: [Workflow template management](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#templates) is now in the Projects section of the Encord app.

  * **Numerical Ontology Type**: We've introduced a new [Classification and Attribute type](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#classifications) to the Ontology: Numerical. This field accepts only numerical input.

  * **Pixel Measurements**: We added a [new setting](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts#drawing-settings) that allows you to view the source pixel size in the interface, making it easier to estimate object dimensions before adding or adjusting labels. In addition, there's an option to automatically include the pixel area of objects in their titles.
</Update>

<Update label="August 14">
  * **[Task Actions](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-actions)**: All task actions have been unified into a single **Actions** menu. This new menu supports hotkey-driven workflows, which improves the user experience and the speed at which you can assign tasks, change priorities, and move tasks.

  * **[View Mode](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#view-tasks)**: Admins and team managers can use the new view mode to access tasks from any Workflow stage. View mode prevents you from accidentally editing labels or grabbing tasks from your teammates, allowing you to audit team work and review progress without interrupting others. You can easily switch from view mode to edit mode at any time, allowing you to view labels without first initializing a task.

  * **[Entity User Management](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#manage-project-collaborators)**: We've improved the user experience for managing users in Projects, Datasets, and Ontologies. This makes adding and removing users faster and provides a clearer overview of user roles for each entity.
</Update>

<Update label="August 6">
  * **Label Export UI**: [A new Export button and simplified modal](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels#recommended) lets you export labels from any tab within a Project. This makes the exporting process faster and more convenient.

  * **[Synchronized Group Playback](/platform-documentation/Annotate/annotate-label-editor/multimodal-groups#synchronize-playback)**: You can now synchronize playback for all videos and audio files within a Data Group, ensuring all media plays simultaneously and in sync when triggered.

  * **[Simplified Group Timeline](/platform-documentation/Annotate/annotate-label-editor/multimodal-groups#single-editor-timeline-setting)**: A new setting allows you to display a single, consolidated timeline for the entire Data Group, showing only the annotations for the data unit currently being annotated or reviewed. This simplifies navigation for complex multi-file tasks.
</Update>

<Update label="July 17">
  * **[Email Updates](/platform-documentation/General/general-workspace-analytics#org-analytics-emails)**: You can now subscribe to receive Workspace Analytics email updates weekly or monthly, ensuring you stay informed with what happens in your Workspace.

  * **[Share the Workspace Analytics](/platform-documentation/General/general-workspace-analytics#share-org-analytics)** You can now share a link to the Workspace Analytics directly with other Workspace admins, streamlining collaboration and insight sharing.

  * **Data Groups (BETA)**: We're excited to announce early access to [Data Groups](/end-to-end/Features/e2e-data-groups)! This feature lets you organize individual files into custom groups, making them easier to annotate and review together. This natively enables multi-tile and multi-modal workflows.

    * **Enhanced Management**: Data Groups provide improved file list views, streamlined Project queues, and integrated analytics, allowing you to manage multiple files per task.
    * **Flexible Layouts & DICOM Support**: Apply layouts at the group level to create diverse annotation arrangements within a single Project. This also includes new support for **DICOM series**, expanding modality capabilities.
    * **Backward Compatibility**: Label exports from Data Groups remain compatible with previous Editor Layouts functionality.

    Contact support to gain access to data groups.

  * **Invitations & Resource Management (BETA)**: We’ve updated the UX around managing users in your Workspace and assigning them to resources across Encord, providing better visibility and control over user onboarding.

    * **Streamlined User Distinction**: We've removed the "internal" versus "external" user distinction, simplifying user categorization.
    * **New Workspace-Level Roles**: Introducing two new organization-level roles for improved user management:
      * **Workforce Manager**: Ideal for those managing external teams or labeling vendors.
      * **Collaborator**: A role with limited access, designed for external users or internal annotators and reviewers.
    * **Centralized Project Assignment**: You can now assign users to Projects directly from the Workspace settings page. Simply click 'User Details' to assign a user to one or multiple Projects.
    * **Simplified User Removal**: The 'User details' screen is now also your consolidated location for **removing users from your workspace**.

  - **[Editable Workflows](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#editing-workflows)**: You now have the ability to edit the Workflows of existing Projects providing increased flexibility to adapt your annotation processes as Project needs evolve.
  - **[Flexible Task Movement](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#move-tasks)**: Tasks can now be flexibly moved to any stage of the Workflow, providing greater control and adaptability in managing your Project.
</Update>

<Update label="June 11">
  * **Data Registration**: We've expanded the automated [cloud synced folder functionality](/platform-documentation/Curate/add-files/index-register-cloud-data-cloud-sync) to cover all single file data types, now including **audio, PDF, and text files** alongside visual data. This enhancement eliminates the need for manual SDK data uploads and separate JSON file processes, immensely reducing the time it takes to register your data with Encord. Note that DICOM and image groups are still not supported in cloud-synced folders.

  * **Cloud Synced Folders SDK**: You can now create and sync cloud-synced folders using the SDK, enabling you to manage their entire lifecycle [programmatically](/sdk-documentation/index-sdk/sdk-files-and-folders#cloud-synced-folders).

  * **Workspace Analytics**:The new [Workspace Analytics](/platform-documentation/General/general-workspace-analytics) provide actionable insights into your Workspace's performance and activity, including:
    * **Activity**: Monitor overall organizational engagement.
    * **Collaborators**: Offers analytics for each organization member across all Projects.
    * **Projects**: Provides analytics for all Projects in your Workspace.

  * **Annotator Training**: You can now use workflow Projects to create annotator training Projects for assessing and upskilling your annotation workforces. This was previously only possible using the now deprecated Manual QA Projects.

  * **Centralized Project Tag Management**: Create, manage, and track all your [Project Tags](/platform-documentation/General/general-workspace-settings#project-tags) in a single, consolidated view. Project tags help you easily group and find your Projects. Additionally, you can track and analyze your Projects by tags within the new Workspace Analytics.

  * **Nested Classifications Behavior**: Nested classifications and attributes are now closed by default. This change makes deeply nested Ontologies more manageable and improves the initial look of complex annotation interfaces. For those who prefer the previous behavior, a new option in the [Label Editor settings](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts#general-settings) allows you to revert to the always-expanded view.

  * **Relation Attributes**: We've improved the [Relation Attributes](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#relation-attributes) user experience. Objects linked using Relation Attributes now display arrows, visually indicating their relationship and making it easier to understand that object labels are connected.

  * **Multiple Label Selection**: Multiple labels can now be selected and reviewed at the same time, accelerating your review workflows.

  * **SDK Timers**: Programmatically use [SDK timers](/sdk-documentation/projects-sdk/sdk-projects-timers) to view the time spent on your Projects, Stages, Tasks, individual Users, and more. This granular control provides valuable insights for optimizing your annotation workflows.

  * **Issues & Comments SDK**: You can now add and manage [issues and comments](/sdk-documentation/projects-sdk/sdk-projects-issues-comments) directly using the SDK.

  * **Project Status SDK**: [Programmatically change the status](/sdk-documentation/projects-sdk/projects-and-workflows/sdk-project-status-change-status) of your Projects with the SDK.

  * **Agent Action Tracking SDK**: We've added `last_actioned_by` to agents, providing better visibility into which agent performed the last action on a task.

  * **SDK Support for Cloud Synced Folders**: You can now create and sync cloud-synced folders [using the SDK](/sdk-documentation/index-sdk/sdk-files-and-folders#cloud-synced-folders).
</Update>

<Update label="May 02">
  * The **Issues** feature is now officially out of Beta and fully released. Features include:
    * **[Issue tags](/platform-documentation/General/general-workspace-settings#issue-tags)**: can be applied to issues and can be tracked in the [Project Analytics](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics). Built for project admins and team managers, this part of the Issues feature focuses data-driven quality monitoring and enables better team training and labeling guideline improvements.
    * **[Issues & comments](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review#issues-and-comments)**: Users can add **Issues** to annotation and review tasks to streamline communication and feedback without sacrificing speed. Each issue supports **comment threads** linked to a specific label, an entire task, a specific frame, or a precise canvas location.
      <Note>
        An end-to-end guide for working with issues can be found [here](/end-to-end/Features/issues-e2e).
      </Note>

  * **Encord Agents**: We've removed `opencv-python` as a required dependency. Instead, `opencv-python-headless` is now included in the optional `encord-agents` package. This change reduces bundle size and improves compatibility with serverless environments, which is especially useful for Agents.  If you're using features that rely on visual dependencies (for example `dep_single_frame`, `dep_video_sampler`), make sure to include the appropriate [dependency version](https://github.com/encord-team/encord-agents/releases/tag/v0.2.0). A warning message appears if it's missing.

  * **Search by `data_hash`**: You can now search by `data_hash` in the task queue to access a particular task directly, and identify which Workflow stage a specific data unit is in. This makes debugging and tracking progress more efficient.

  * **Workforce Management**: A new [**Workforce Manager** user role](/platform-documentation/Annotate/annotate-settings-general#workforce-manager) is now available at the Workspace level, enabling your 3rd-party workforces to self-organize without the need for Workspace admin involvement. Workforce managers:

    * Can create and manage user groups
    * Add user groups to Projects they are an Admin or Team Manager of
    * Can only view Workspace admins and users they’ve personally invited, and see groups they’ve created or have been assigned to as a manager.

    <Note>
      The Workforce Manager feature is available in [Encord Labs](/platform-documentation/Annotate/annotate-settings-general#encord-labs).
    </Note>
</Update>

<Update label="April 24">
  * **Enhanced Metadata Support for Text and PDF Files**: You can now include [`textMetadata`](/platform-documentation/Curate/add-files/index-register-cloud-data#text-metadata) and [`pdfMetadata`](/platform-documentation/Curate/add-files/index-register-cloud-data#pdf-metadata) in your JSON files when uploading from cloud storage. These fields let you specify values such as file size directly, eliminating the need for Encord to retrieve them during upload or registration. This significantly speeds up data imports and supports strict client-only access for sensitive text and document workflows.

  * **Updated Timer Analytics**: We've improved Encord's native time tracking to now measure to the nearest second, up from 15-second intervals previously. Our timing algorithm has been tuned to better accounts for inactivity during annotation tasks. The native timer data appears on [dashboards](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics) within 5 minutes of recording.

  * **[Editor Settings Template (*Beta*)](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-settings-shortcuts#label-editor-settings-templates)**: Project Admins can now create and apply Editor Settings Templates to ensure all users in a Project start with consistent configurations. Users can still switch to personal settings if needed, and templates can be saved for future use across Projects. Contact your customer success manager to gain access to editor settings templates.
</Update>

<Update label="April 08">
  * **Workspace Admins Can Remove Project Admins**: Workspace admins can now remove Project admins from the list of collaborators in Projects.

  **Multi-Tile UX Improvements**: We've enhanced our multi-tile annotation and review workflows for increased efficiency and accuracy:

  * **Minimizable Accept/Reject Modal**: The **Accept/Reject All Labels** modal in the frame view can now be minimized to prevent it from obscuring media.
  * **Hotkey for Tile Navigation**: Use <kbd>Option</kbd> + <kbd>S</kbd> on Mac, or <kbd>Alt</kbd> + <kbd>S</kbd> on Windows to quickly cycle through annotatable/reviewable tiles.
  * **Persistent Scroll Position**: The left-side panel’s scroll position remains intact when switching focus between tiles, preventing loss of context.
  * **Stable Panel Width**: The width of the left-side panel now persists after adjustments, ensuring a consistent view across tasks.
  * **Improved Video Playback**: Videos now replay using the **space bar** without needing to reset to the first frame manually.
</Update>

<Update label="March 31">
  * **Polygon Enhancements**: The Polygon Pane now opens automatically when clicking or creating polygons in the Label Editor, providing easy access to essential editing tools. Users can:

    * Add vertices seamlessly.
    * Create polygons using the Polygon Brush.
    * Toggle *Move Mode* to reposition entire polygons.
    * Duplicate polygons in place for precise adjustments.
    * Instantly access the eraser tool.
    * Drag vertices to refine shapes with greater control.

    These improvements make polygon editing more intuitive and efficient, streamlining the annotation workflow.

  * **Bulk Class Change**: Easily update multiple label classes at once by selecting several labels and changing their class in bulk using the hotkey `c` or th. This streamlines the workflow and improves efficiency.

  * **Improved Label Navigation and Selection**: Navigating and managing labels is now more seamless, making it easier to work with complex projects.
    * Finding and interacting with labels is now more intuitive, especially for Projects with many labels.
    * Hovering over a label in the left panel highlights the corresponding object on the canvas.
    * Selecting a label in the panel now selects it on the canvas, improving navigation clarity.
    * Multiple selected labels are visually distinguished with a blue outline and an enclosing box.
    * The right-click context menu has been reorganized for better visibility and easier access to actions.
</Update>

<Update label="March 13">
  These release notes include editor related features released since the start of 2025.

  * **[Comments & Issues (BETA)](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#issues-and-comments)**: Users can now add **issues** to annotation and review tasks to communicate with other users. Issues support **comment threads** that relate to the entire task or specific sections. A notification badge indicates unresolved issues, which can be filtered by *Resolved* and *Unresolved*. Issues can be attached to a task, a specific frame, or a precise location on the canvas. Additionally, **rejection issues** provide clear feedback when a reviewer rejects a task, ensuring better communication and annotation quality. This feature is in BETA. Contact the Encord team to try this feature.
  * **Improved multi-tile review flow**: Introducing read-only tiles (for example for prompts), and quick switching between focused tiles with a new hotkey.
  * **Ontology descriptions**: Add descriptions to elements in your Ontology so that they’re easily available as hints to annotators and reviewers.
  * **[Task Pre-Fetching](/platform-documentation/Annotate/annotate-projects/annotate-project-settings#preload-next-task)**: A new setting enables the Label Editor to pre-load the next image in the queue, significantly reducing wait times and ensuring a seamless workflow when moving between image tasks.

  ***

  * **Complex Polygon Support**: The Label Editor now supports complex polygons, improving annotation capabilities for intricate shapes such as polygons with holes in them.
  * **Bulk Polygon Operations**: Performance enhancements enable efficient handling of hundreds of polygons at once.
  * **[Polygon Subtraction & Merging](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#edit-polygons-and-polylines)**: New tools allow for subtracting and merging polygons, improving shape manipulation capabilities.
  * **Polylines with Arrows**: Users can now add directional arrows to polylines, for cases where vector and direction are important.
  * **Locking objects**: In order to avoid accidentally adjusting existing objects, you can now lock them in place and make them unselectable on the canvas.
  * **Layers and ordering upgrade**: Layers are much more obvious with ordering in the left panel, and the ability to choose the exact object you want when clicking in an overlapping area.
  * **Selection UX enhancements**: When selecting objects you can see how many objects, and precisely which objects are selected using a count and a subtle enclosing box.
  * **Square brush**: Use brush tools in bitmask or polygon editing with a square brush.
  * **Quick erase UX**: Enable eraser quickly with an added hotkey within editing mode.

  ***

  * **SAM on MPR Volumes**: The Segment Anything Model (SAM) can now be used on MPR DICOM volumes, expanding AI-assisted annotation capabilities.
  * **Improved Editor Performance for Large DICOM Volumes**: Rendering optimizations ensure a smoother experience when working with large DICOM Datasets, particularly for sample perceptive data.
  * **Scroll locking**: We introduced a toggle to synchronize scrolling between series. Helpful for comparing treatment effects, or with reference studies.
</Update>

<Update label="March 12">
  These release notes include platform related features released since the start of 2025. Look out for our Editor Release Notes tomorrow for more updates!

  * **[Cloud-synced folders (BETA)](/platform-documentation/Curate/add-files/index-register-cloud-data-cloud-sync)**: Register your cloud data by syncing your cloud storage bucket directly with Encord. This feature is in BETA. Contact the Encord team to try this feature.
  * **Improved Error Handling for Cloud Uploads**: We've enhanced error handling for data uploads from cloud storage to Encord. When issues are detected in the upload JSON, users now receive clearer, more informative error messages, making troubleshooting and resolving upload issues easier.
  * **File Downloads**: Users with the necessary permissions can now download files directly from the **Sources** interface, making it easier to access and reference files when needed.
  * **[COCO Exporter](/platform-documentation/Annotate/annotate-export/annotate-export-coco)**: We've updated the COCO exporter, which now includes complex polygons.

  ***

  * **[Updated Project Analytics Dashboard](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics)**: We've upgraded our Analytics tab to a scalable, event-based system, offering:
    * **Workflow and Agent-native performance metrics** to track efficiency and quality.
    * **Advanced filtering** for deeper insights and more precise comparisons.
    * **Upgraded CSV exports** for seamless external reporting and analysis.

  ***

  * **[Move Tasks Directly to Complete / Archive](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-queue-%26-workflow)**: Tasks can now be directly moved to the "Complete" or "Archive" stage in the UI, bypassing unnecessary steps.
  * **New Filters for Task Queue**: Users can now filter the task queue the presence or absence of comments, and *unassigned* status, making it easier to manage and locate tasks.
</Update>


# 2026
Source: https://docs.encord.com/release-notes/releasenotes-2026

Product Updates and Announcements 2026

<Update label="September 8">
  * **[Task Rules](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-rules)**: Automated in-editor validation for labels are now in General Availability, giving annotators instant feedback and flagging areas for reviewers to check. Rules can be set as "blocking" (submission requires compliance) or "warning" (violations are flagged but submission is allowed).
</Update>

<Update label="September 2">
  * **[Metadata Router](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#metadata-router)**: The new metadata metadata router workflow stage is now in General Availability. It lets teams define rules that route tasks based on metadata values, such as sending high-priority items to specific annotator pools, directing data classes to particular annotation stages, or splitting labels into different output buckets - eliminating the need for manual triage or custom orchestration. This feature is only available to Curation Package customers.
  * **[Task-Ready Notifications for Custom Agents](/platform-documentation/Annotate/automated-labeling/annotate-custom-agents#configure-batched-webhook-notifications)**: Custom Agents running in Advanced mode can now register a webhook URL to receive a signed POST notification once a task batch is ready, based on batch size or max wait threshold. This eliminates the need for constant polling or one-at-a-time inference, reducing infrastructure costs.
</Update>

<Update label="August 14">
  * **Folder Tags**: Folders can now be tagged, making it easier to organize and maintain a library of Datasets and Projects. Folder tags share the same underlying database table as Project tags.

  * **Persistent Folder State**: Folder selections in the Files & Folders view now persist when switching to the Explore tab, preserving context during navigation.
</Update>

<Update label="August 13">
  * **[PCD Labeling Updates](/platform-documentation/Annotate/annotate-label-editor/annotate-pcd)**:
    * **1-Click Segmentation**: Click on a group of points in 3D to automatically generate a segmentation cluster.
    * **1-Click Cuboid**: Click on a group of points in 3D to automatically generate a cuboid.
    * **Smart Interpolation**: Track a cuboid across time by clicking on a group of points, automatically computing its path and velocity for efficient annotation.

  * **[Merlin updates](/platform-documentation/GettingStarted/encord-merlin)**:
    * **Merlin in the Encord Platform**: Merlin is now natively available in the Encord platform, no longer requiring a separate Claude/MCP setup. Access it from the homepage, global search, or a new dedicated Merlin page, with full chat history and all MCP tools available from day one.
    * **Encord Docs Tool**: Merlin can now answer platform questions directly, such as "how do I set up a consensus workflow?", with grounded responses and doc links, available in both MCP and in-platform chat.
    * **Update Project Status**: Merlin now supports updating project status directly.
    * **Dry-Run Previews for Ontology Changes**: Preview the exact impact of ontology creation, edits, and editor layout changes, including which fields would be archived, before committing changes.
    * **Dataset-Level Analytics**: Merlin now provides throughput, quality, and rejection rate analytics scoped to individual datasets rather than entire projects.
    * **Comment Thread Analytics**: List comment threads and view grouped comment/issue event counts directly through Merlin.

  * **What's new drawer**: Select the megaphone in the main navigation to view product updates. A dot appears when there are updates you have not viewed. The drawer shows up to ten updates and links to the release notes for the full history.
</Update>

<Update label="August 4">
  * **Annotation-Level Issues**: Create issues on a specific object instance or classification using a new SDK method, optionally scoped to specific frame ranges and `space_id`. This allows QA findings to be tied directly to the offending label rather than a frame or point coordinate.

  * **Issues Improvements**:
    * Annotation issues now display as clickable chips showing the label name and flagged frames in the Label Editor. Clicking a chip jumps to the relevant frame and highlights/centers the flagged instance.
    * A smoother [Issues](/persona-taskers/tasker-annotate-review-issues#issues-in-tasks) panel with a merged label badge (tag + exact label name), muted headings, inline frame chips, and a simplified tag icon.
</Update>

<Update label="July 31">
  * **Map View Zoom**: Users can now continually zoom into clusters of data down to individual data points, even for extremely large datasets, augmenting the previous box-drawing method with a more natural, fluid navigation experience when exploring your data.
</Update>

<Update label="July 30">
  * **[Label Checkpoint Workflow Node](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#label-checkpoint)**: Save the current status of labels onto a new branch, enabling label versioning after a Pre-labelling Agent or Export Node.

  * **[Label Branch Visualisation](/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-annotate#branch-overlay-labels)**: Compare labels from different branches directly in the Editor. Supports assessing pre-label accuracy, viewing consensus labels in Complete, and benchmark evaluation for annotator training.
</Update>

<Update label="July 24">
  * **[Live project editing with Merlin](/platform-documentation/GettingStarted/encord-merlin)**: Merlin can now edit live Projects, not just spin them up. Workflows, Ontologies, editor layouts, and task priorities are all editable after creation. We've also added richer analytics (per-task time, org-wide summaries), as well as better custom-layout support (side-by-side comparisons, conditional visibility).
</Update>

<Update label="July 22">
  * **Automatic Ground Detection**: Encord can now [automatically fit a mesh](/platform-documentation/Annotate/annotate-label-editor/annotate-pcd#ground-mesh-fitting) across the entire scene in one pass, following the natural curves and dips of real-world terrain. This also unlocks a set of smart, TPT-reducing features for 3D scenes, including 1-click cuboids, automatic cuboid tracking, and automatic detection and removal of static objects.

  * **Data Explorer Split View**: When exploring your data, the embeddings, analytics, and geolocation views now appear side by side with the grid view, so you can see which files belong to a given data cluster without switching between views.
</Update>

<Update label="July 15">
  * **Project Overview**: The default [Project Overview tab](/platform-documentation/Annotate/annotate-projects/annotate-project-analytics#overview) now gives you more useful information at a glance. New users get guided setup steps to get a Project started faster, while experienced users get deeper insights into how the Project is progressing.
    * Insights: Workflow stage bar charts are replaced with a more detailed view with clickable nodes that take you straight to the queue, plus top created classes and top issue tags to help spot trends.
    * Task layout: Preview the task layout without opening the queue, and the customization option is now more prominent.
    * Setup guidance: The tab now flags when an Ontology or data is missing, lets you switch the linked Ontology if no labels exist yet, and makes it clearer that clicking a template creates a Project.

  * **Project Data Management:** We've made adding and managing data in Projects a more unified experience, available when creating a Project (Data tab), from the Project overview (Manage button on the Data card), or in the Workflow editor (start node). From there, you can search and preview folders and Datasets by thumbnail, add data at the granularity you need.

  * **Geospatial Map Navigation**: [Exploring large geospatial](/platform-documentation/Curate/index-map-view) datasets is now faster and easier. Clicking a cluster zooms into a tight bounding box around it, progressively narrowing until individual points resolve and can be opened directly in a preview modal. A new style picker lets you switch between Map, Satellite, and Terrain views without resetting your camera position or losing any rectangles you've drawn. The map also now opens in cursor mode by default (rather than draw mode), so you can pan and click straight away. Together, these let you drill from a cluster down to a single item with clicks alone, and cross-check context across map styles.
</Update>

<Update label="July 10">
  * **Add attributes in bulk**: [Set attributes](/platform-documentation/GettingStarted/gettingstarted-labeling#adding-attributes) on multiple selected objects at once in the Label Editor, instead of editing labels one by one.

  * **Custom Layout Updates:** [Custom layouts](/platform-documentation/Annotate/annotate-projects/custom-layouts#custom-layouts) now support objects natively, rendered as a table. You can also conditionally render form elements based on answers to other elements, enabling dynamic forms that adapt as users fill them in.
</Update>

<Update label="July 6">
  * **[Drag & drop for carousel Data Group](/platform-documentation/Annotate/annotate-label-editor/multimodal-groups#rearrange-tiles-with-drag-and-drop)**: When working with a carousel Data Group, you can now drag items from the carousel strip directly into any mosaic tile pane, making it easy to arrange media across your multi-tile layout.

  * **[Peer annotation markers](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus#peer-annotation-gating)**: In consensus Workflows, annotators can now mark sections of the timeline as valuable, pointing other annotators straight to the frames that matter and saving them from combing through the whole video. When enabled, peer annotators are also blocked from starting their subtask until the first annotator completes theirs, ensuring they can view the initial annotation before adding their own. Currently video-only.

  * **[Custom Layout improvements](/platform-documentation/Annotate/annotate-projects/custom-layouts)**: We've made several improvements to the Custom Layout:

    * **Edit classifications inline**: You can now edit your classifications in the ontology directly from the Custom Layout page.
    * **Improved drag & drop**: Drag & drop is now more intuitive.
    * **Easier item adding**: Adding items is now much easier with a new popup menu.
    * **Configurable editor deprecated**: The old configurable editor is being fully deprecated. All Projects that previously used it have been migrated to the new Custom Layout.

  * **New Viewer Role**: We've introduced a new [Viewer role](/platform-documentation/Annotate/roles-and-permissions) for Projects, giving users read-only access to the queue, analytics, and editor, while still allowing them to create and comment on issues. Contact Encord support to enable this feature.
</Update>

<Update label="June 24">
  * **[Custom Agent Pathways](/platform-documentation/Annotate/automated-labeling/annotate-custom-agents#custom-agents-in-the-agents-catalog)**: Custom Agents can now have multiple decision pathways, allowing you to route tasks based on the agent's response. This enables more complex workflows and decision-making processes within your Project's Workflow.
</Update>

<Update label="June 23">
  * **Video annotation instructions**: Annotation instructions now support video files, allowing you to provide detailed visual guidance to annotators. Video instructions can be viewed directly in the Label Editor during annotation.
</Update>

<Update label="June 19">
  * **[Merlin - Encord's MCP (BETA)](/platform-documentation/GettingStarted/encord-merlin)**: Introducing Merlin, a new Encord MCP server that allows you to access Encord directly from your IDE or AI tool.
</Update>

<Update label="June 5">
  * **[Audio editor improvements](/platform-documentation/Annotate/annotate-label-editor/annotate-audio)**:

    * **Multi-select and bulk actions**: Select multiple segments and perform bulk actions in the audio editor.
    * **Improved hotkeys, snapping, and undo/redo**: Faster keyboard shortcuts, snapping controls, and more reliable undo/redo functionality.
    * **Inline transcripts**: Ranges now display real speaker names instead of generic Speaker (1) labels.
    * **Spectrogram view**: A new spectrogram view is available for finer-grained audio annotation.
    * **[Dynamic transcripts](/platform-documentation/Annotate/annotate-label-editor/annotate-audio#audio-transcription)**: Audio regions can now be added using the timeline by dragging, then adjusted or deleted as needed.
</Update>

<Update label="June 3">
  * **New Project creation flow**: [Streamlined Project creation](/platform-documentation/GettingStarted/gettingstarted-create-project#create-from-a-template) with a step-by-step wizard and more than 10 ready-to-use templates for common tasks. This simplifies the process of setting up new Projects and provides a preview of the editor layout and ontology before you start.
</Update>

<Update label="June 2">
  * **[Custom Layouts](/platform-documentation/Annotate/annotate-projects/custom-layouts)**: Design your own annotation editor layouts with drag-and-drop functionality. Arrange media players, classification fields, and input controls exactly how your annotators need them through an intuitive visual interface with no code required.
</Update>

<Update label="June 1">
  * **Export labels to cloud storage**: Users can now add a Label Export node to their Workflow to automatically [export labels directly to their cloud storage](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels#export-labels-to-cloud-storage-recommended).
</Update>

<Update label="May 21">
  * We've redesigned the Encord platform around two clear concepts: Data and Projects. Data is where you manage, curate and explore all your data across all your folders and Datasets in one place. Projects is where your annotation and eval workflows live.

    * Data: Manage and explore all your data in one place
    * Projects: Label exploration (formerly Active) is now in one place with annotation workflows, accessible on the Project page under Explorer
</Update>

<Update label="May 14">
  * **Add data from Index to Projects directly**: Users can now select data within Index and add it directly to a Dataset or Project. This streamlines Dataset and Project creation and dramatically improves performance when adding millions of items.
</Update>

<Update label="May 13">
  * **Consensus Agreement Tables**: You can now track annotator agreement and reviewer alignment directly in the Analytics for Review and Refine Consensus Projects.
</Update>

<Update label="April 30">
  * **Continuous data flow**: Connect a cloud storage folder directly to your Project and keep it automatically in sync. New files are added as they arrive. Filters can be used to control exactly which files land in your Project.

  * **Issues filtering**: Reviewers can now filter [Issues](/persona-taskers/tasker-annotate-review-issues) by object class and comment keyword, making it significantly easier to triage and action feedback on tasks with large volumes of detailed issue threads.
</Update>

<Update label="April 27">
  * **Hide annotator usernames in Consensus Review**: Admins can now toggle a Project setting to hide annotator usernames during consensus review tasks, making it impossible to identify who created each label or correspond labels to the same annotator within a task thereby preventing reviewer bias.

  * **Scrollable data group grids**: Large Data Groups no longer force tiles to shrink to an unusable size. Use the new **Data group scrollable tile threshold** Editor setting to activate scrolling automatically. Grids below the threshold stay fixed, while larger ones become scrollable with a persistent scrollbar. Also enables scrolling within individual tiles, such as long text files.

  * **Hide all approved labels**: Reviewers can now instantly hide all approved labels with a single toggle, making it easier to focus on pending work without distraction.
</Update>

<Update label="April 24">
  * **[Auto Data Groups](/platform-documentation/Curate/data-groups/index-data-groups#auto-data-groups)**: Now generally available to all customers. Simply select a source folder and Encord analyzes the files, suggest grouping rules, and automatically creates Data Groups without requiring SDK scripts or manual intervention.
</Update>

<Update label="April 16">
  * **[Agents in Workflows](/platform-documentation/Annotate/automated-labeling/annotate-agents-usage#in-the-workflow)**: Agents from the [Agents Catalog](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview#agent-catalog) can now be added as nodes in your Workflows and run directly from the [Project Queue](/platform-documentation/Annotate/automated-labeling/annotate-agents-usage#agent-task-management). Previously, agents could only be triggered manually from the Editor or required extensive custom setup.

  * **[Webhook Signature Verification](/platform-documentation/Annotate/annotate-webhooks-notifications#verifying-webhook-signatures)**: Every webhook request from Encord now includes signature headers so you can verify that requests genuinely originated from Encord and have not been tampered with. Verification is optional but recommended for production integrations.
</Update>

<Update label="April 9">
  ## Metadata Panel for Taskers

  * **View Metadata**: Users can view task metadata directly within the Label Editor using a new metadata panel. You can now:
    * Toggle the panel on or off using the new button
    * Copy data directly from the panel
    * Click URLs to open them in a new tab
    * Panel content updates automatically based on the active tile in a Data Group
</Update>

<Update label="March 27">
  * **[Labels in Index (General Release)](/platform-documentation/Curate/index-label-filtering)**: Now available to all Index customers, enabling label-based exploration and filtering across entire Datasets. View and compare ground truth labels and model predictions with visual previews of bounding boxes, polygons, and other label types.
</Update>

<Update label="March 19">
  * **Improved review UX for consensus classifications**:
    * Easier label selection; clear visibility of annotator agreements
    * Toggle between "By annotator" and "By label" modes
    * Expand/collapse functionality for efficient classification review.
</Update>

<Update label="March 13">
  * **[Data Groups (General Release)](/platform-documentation/Curate/data-groups/index-data-groups)**: You can now create, manage, and label multiple files as a single task with Encord’s Data Groups. This release introduces instant interactions across tiles, cross-tile instances for consistent object labeling, global classifications, and flexible tile management. Data Groups is a powerful and intuitive way to build complex labeling tasks with different types of media.
</Update>

<Update label="March 5">
  * **Agents Catalog**: You can now browse, [configure, and deploy pre-built agents directly in Encord](/platform-documentation/Annotate/automated-labeling/annotate-agents-overview) with zero code required. The Agents Catalog makes automation accessible with no engineering resources, self-hosted services or custom API integrations needed. Custom agents remain fully supported alongside the new catalog.
</Update>

<Update label="February 3">
  * **SAM 3 (General Release)**: [SAM 3](/platform-documentation/Annotate/automated-labeling/annotate-sam) has now graduated from early access and is available to all customers with SAM access.
</Update>

<Update label="January 27">
  * **SAM 3 (Early Access)**: You can now [detect and label all similar objects based on an existing label](/platform-documentation/Annotate/automated-labeling/annotate-sam#label-all-objects). This works for unusual or highly specific items that SAM 3 may not recognize by name. Detected objects are first created in a preview state and are only recorded as label creation events when you confirm, keeping analytics clean if you start over or discard the results.
</Update>

<Update label="January 22">
  * **Auto-Refresh Cloud Sync Folders**: Cloud-synced folders now refresh automatically once per day, so new files in connected S3 and GCS buckets appear in Encord without manual refreshes or custom automation.
</Update>


# Label Validation Collections
Source: https://docs.encord.com/sdk-documentation/api-active/sdk-active-collections



Collections are saved groups of data units or labels that let you curate subsets of your data and perform bulk actions on them, such as sending items to annotation, running bulk classifications, or exporting a curated Dataset.

## Filter Presets

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

### Create Filter Preset

Create a Filter Preset based on raw JSON.

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

  from encord.orm.filter_preset import ActiveFilterPresetDefinition, 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= ActiveFilterPresetDefinition(global_filters=FilterDefinition(
          filters= [{'key':'<key-name>',
          'include':True or False,
          'values' : [<filter-values>],
          'type': '<client-metadata-type'}]
      )
   ))

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

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

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

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

  # 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="Cherries and Apples",
      filter_preset= ActiveFilterPresetDefinition(global_filters=FilterDefinition(
          filters= [{'key':'Fruit',
          'include':True,
          'values' : ['Cherries', 'Apples'],
          'type': 'client_meta_enum'}]
      )
    )
   )

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

  ```
</CodeGroup>

### Update Filter Presets

<Note>All arguments are optional when updating a filter preset.</Note>

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

  from encord.orm.filter_preset import ActiveFilterPresetDefinition, 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= ActiveFilterPresetDefinition(global_filters=FilterDefinition(
          filters= [{'key':'<key-name>',
          'include':True or False,
          'values' : [<filter-values>],
          'type': '<client-metadata-type>'}]
      )
    )
   )

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


  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

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

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"
  PRESET_ID = "b19d1b00-25e4-467c-acf0-c930e0b74ee1"

  # 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 (with only global_filters, no local_filters)

  # Create a preset with the defined filter preset
  preset = project.get_filter_preset(filter_preset_uuid=PRESET_ID)
  preset.update_preset(
      name="Cherries, Apples, Blueberries",
      filter_preset= ActiveFilterPresetDefinition(global_filters=FilterDefinition(
          filters= [{'key':'Fruit',
          'include':True,
          'values' : ['Cherries', 'Blueberries', 'Apples'],
          'type': 'client_meta_enum'}]
      )
    )
  )

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

  ```
</CodeGroup>

### List Filter Presets

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

<CodeGroup>
  ```python Template theme={"dark"}

  # 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)

  ```

  ```python Example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID = "5fdb3d88-b88c-4a00-8aa9-e7e836024cdd"


  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)

  ```
</CodeGroup>

### Delete Presets

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

```python Template theme={"dark"}

# 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.

<CodeGroup>
  ```python Template theme={"dark"}
  # 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)

  ```

  ```python Example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  from encord.orm.filter_preset import FilterPreset as OrmFilterPreset

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PRESET_ID = "fc8c2d43-d7d5-4f40-a3e4-1bebb7b71d2f"

  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)

  ```
</CodeGroup>

***

## 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.

<CodeGroup>
  ```python Template List ALL Collections theme={"dark"}

  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)

  ```

  ```python Example List ALL Collections theme={"dark"}

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

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  PROJECT_ID = "5fdb3d88-b88c-4a00-8aa9-e7e836024cdd"

  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)

  ```
</CodeGroup>

### List FRAME Collections

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

<CodeGroup>
  ```python Template List FRAME Collections theme={"dark"}

  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)

  ```

  ```python Example List FRAME Collections theme={"dark"}

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

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  PROJECT_ID = "5fdb3d88-b88c-4a00-8aa9-e7e836024cdd"

  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)

  ```
</CodeGroup>

### List LABEL Collections

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

<CodeGroup>
  ```python Template List LABEL Collections theme={"dark"}

  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)

  ```

  ```python Example List LABEL Collections theme={"dark"}

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

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  PROJECT_ID = "5fdb3d88-b88c-4a00-8aa9-e7e836024cdd"

  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()

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

  ```
</CodeGroup>

### Create Collection

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

<CodeGroup>
  ```python Template theme={"dark"}
  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)
  ```

  ```python Create FRAME Collection theme={"dark"}

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

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  PROJECT_ID = "5fdb3d88-b88c-4a00-8aa9-e7e836024cdd"

  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="FRAME Collection 1", description="A useful and meaningful description for the Collection.", collection_type= "FRAME")

  print(collection)

  ```

  ```python Create LABEL Collection theme={"dark"}

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

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  PROJECT_ID = "5fdb3d88-b88c-4a00-8aa9-e7e836024cdd"

  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="LABEL Collection 1", description="A useful and meaningful description for the Collection.", collection_type= "LABEL")

  print(collection)

  ```
</CodeGroup>

### 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.

<AccordionGroup>
  <Accordion title="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:

    <CodeGroup>
      ```python Template Get Data ID  theme={"dark"}

      # 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

      ```

      ```python Example Get Data ID theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

      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

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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

    <CodeGroup>
      ```python Template Get Annotation ID  theme={"dark"}

      # 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

      ```

      ```python Example Get Annotation ID theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

      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

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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.

    <CodeGroup>
      ```python Template FRAMES theme={"dark"}

      # 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.")

      ```

      ```python Example FRAME theme={"dark"}

      # 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, ProjectCollectionBulkItemResponse

      # Define constants
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"
      COLLECTION_ID = "76863c3b-533d-4e67-a09b-ccc81d933674"

      # 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 project
      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="08a38705-0497-4e28-9c0e-d10f1ad150fa", frame=0)])

      # 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.")


      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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.

    <CodeGroup>
      ```python Template LABEL theme={"dark"}

      # 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.")

      ```

      ```python Example LABEL theme={"dark"}

      # 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, ProjectCollectionBulkItemResponse


      # Define constants
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"
      COLLECTION_ID = "578b343b-ecb1-4948-b203-f1446fb9ceab"

      # 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="7be6cfcf-e2d4-494f-98f5-91e5ef1c8d1b", frame=435, annotation_id="4kybTAWK")])

      # 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.")


      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### 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.

![Get Preset ID](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-get-preset-id.gif)

<CodeGroup>
  ```python Template theme={"dark"}

  # 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}.")


  ```

  ```python Example theme={"dark"}

  # 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 = "/Users/chris-encord/sdk-ssh-private-key.txt"

  PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

  COLLECTION_ID = "fdc0775e-2694-4191-946e-c3364d00fdc3"

  PRESET_ID = "65eb2e39-c7a4-4aae-bdc6-cce00efdfedf"

  # 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}.")


  ```
</CodeGroup>

### Remove Items from a Collection

Remove items from a Frame or Label Collection.

<AccordionGroup>
  <Accordion title="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:

    <CodeGroup>
      ```python Template Get Data ID  theme={"dark"}

      # 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

      ```

      ```python Example Get Data ID theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

      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

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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

    <CodeGroup>
      ```python Template Get Annotation ID  theme={"dark"}

      # 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

      ```

      ```python Example Get Annotation ID theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

      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

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Remove Items from FRAME Collections">
    #### Remove Items from FRAME Collections

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

    <CodeGroup>
      ```python Template FRAMES theme={"dark"}

      # 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}.")


      ```

      ```python Example FRAME theme={"dark"}

      # 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 = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

      COLLECTION_ID = "fdc0775e-2694-4191-946e-c3364d00fdc3"

      # 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_items([ProjectDataCollectionItemRequest(data_uuid="08a38705-0497-4e28-9c0e-d10f1ad150fa", frame=0)])

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


      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Remove Items from LABEL Collections">
    #### Remove Items from LABEL Collections

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

    <CodeGroup>
      ```python Template LABEL theme={"dark"}

      # 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}.")

      ```

      ```python Example LABEL theme={"dark"}

      # 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 = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

      COLLECTION_ID = "578b343b-ecb1-4948-b203-f1446fb9ceab"

      # 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="7be6cfcf-e2d4-494f-98f5-91e5ef1c8d1b", frame=435, annotation_id="4kybTAWK")])

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

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### 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.

![Get Preset ID](https://storage.googleapis.com/docs-media.encord.com/static/img/active/active-get-preset-id.gif)

<CodeGroup>
  ```python Template theme={"dark"}

  # 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}.")


  ```

  ```python Example theme={"dark"}

  # 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 = "/Users/chris-encord/sdk-ssh-private-key.txt"

  PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"

  COLLECTION_ID = "fdc0775e-2694-4191-946e-c3364d00fdc3"

  PRESET_ID = "65eb2e39-c7a4-4aae-bdc6-cce00efdfedf"

  # 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}.")


  ```
</CodeGroup>

### List all Items in a Collection

<AccordionGroup>
  <Accordion title="List All Frames in a Collection">
    #### List all Frames in a Collection

    Lists all FRAMES in a Collection.

    <CodeGroup>
      ```python Template theme={"dark"}

      # 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}")  

      ```

      ```python Example theme={"dark"}

      # 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 = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"
      COLLECTION_ID = "fdc0775e-2694-4191-946e-c3364d00fdc3"

      # 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}")  

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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.

    <CodeGroup>
      ```python Template List Annotations in Collection theme={"dark"}

      # 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}")  

      ```

      ```python Example List Annotations in Collection theme={"dark"}

      # 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 = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "2dd135b6-0ab2-49b1-9b38-b5c685107790"
      COLLECTION_ID = "578b343b-ecb1-4948-b203-f1446fb9ceab"

      # 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}")  

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>


# Create Datasets
Source: https://docs.encord.com/sdk-documentation/datasets-sdk/sdk-create-and-view-datasets



## Create Datasets

<Note>Creating a Dataset and adding files to a Dataset are two distinct steps. [Click here](/sdk-documentation/index-sdk/sdk-add-files-to-datasets) to learn how to add data to an existing Dataset.</Note>

<Info>Datasets cannot be deleted using the SDK or the API. Use the Encord platform to delete Datasets. </Info>

The following example creates a Dataset called “Houses” that expects data hosted on AWS S3.

* Substitute `<private_key_path>` with the file path for your private key.
* Replace "Houses" with the name you want your Dataset to have.

<CodeGroup>
  ```python Example code theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import StorageLocation

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

  # Create a new dataset
  dataset_response = user_client.create_dataset(
      dataset_title="Houses",
      dataset_type=StorageLocation.AWS,
      create_backing_folder=False,
  )

  # Prints a CreateDatasetResponse object. Verify the Dataset creation
  print(dataset_response)

  # Print the storage location
  print(f"Using storage location: AWS")
  ```

  ```python Example output theme={"dark"}
  {
  {'title': 'Houses', 'type': 1, 'dataset_hash': 'd2bbbaed-cf33-4583-81b5-f30691abde1d', 'user_hash': 'iaDJxNNrMuQMtFPcP9oszw2OCHm2', 'backing_folder_uuid': UUID('5f8364e8-8ccd-4f9f-9066-91e055da920d')}
  }
  ```
</CodeGroup>

***

## Create a Dataset from Label Rows

Use the following script to create a new Dataset from the label rows of a specific Project.

* Replace `<private_key_path>` with the path to your private key.
* Replace `<project_hash>` with the hash of the Project containing the data units you want to create a new Dataset from.
* Replace `My new Dataset` with the name you want to give your new Dataset.

<Warning>
  If `create_backing_folder` is `True`, a mirrored Dataset is created. Mirrored Datasets sync the content of the backed Folder with the Dataset.
</Warning>

```python theme={"dark"}
# Import dependencies
from encord.orm.dataset import StorageLocation
from encord.user_client import EncordUserClient


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

# Specify a Project
project = user_client.get_project("<project_hash>")

# Get the UUIDs of the items to be added to the new Dataset
item_uuids = [lr.backing_item_uuid for lr in project.list_label_rows_v2() if "subset_me" in lr.data_title]

# Create new Dataset and link the items
response = user_client.create_dataset(
    dataset_title="My new Dataset",
    dataset_type=StorageLocation.CORD_STORAGE,
    create_backing_folder=False
)
dataset = client.get_dataset(response.dataset_hash)
dataset.link_items(item_uuids)
```

***

## List existing Datasets

Use the [EncordUserClient](/sdk-documentation/sdk-references/user_client) method to query and list the user client's Datasets.

The following example fetches all Datasets available to the user. Substitute `<private_key_path>` with the file path for your private key.

<Tip>
  The Dataset hash can be found within the URL once a Dataset has been selected:
  `app.encord.com/projects/view/\<dataset_hash>/summary` or `app.us.encord.com/projects/view/\<dataset_hash>/summary`
</Tip>

<CodeGroup>
  ```python View all Datasets theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

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

  # List existing Datasets
  datasets = user_client.get_datasets()
  print(datasets)
  ```

  ```python View all Datasets starting with "Validation"  theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

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

  # List existing Datasets
  datasets = user_client.get_datasets(title_like="Validation%")
  print(datasets)
  ```

  ```python Example output theme={"dark"}
  [
      {
          "dataset": DatasetInfo(
                  dataset_hash="<dataset_hash>",
                  user_hash="<user_hash>",
                  title="Example title",
                  description="Example description ... ",
                  type=0,  # encord.orm.dataset.StorageLocation
                  created_at=datetime.datetime(...),
                  last_edited_at=datetime.datetime(...)
              ),
          "user_role": DatasetUserRole.ADMIN
      },
      # ...
  ]
  ```
</CodeGroup>

<Info>The *type* attribute in the output refers to the `StorageLocation`</Info>


# Re-encoding Videos (SDK)
Source: https://docs.encord.com/sdk-documentation/datasets-sdk/sdk-re-encoding



You can use Encord's Python SDK to re-encode videos. See our [detailed documentation on re-encoding](/platform-documentation/General/general-supported-data#re-encode-videos) for more information.

<Note>If you data is hosted on a private cloud, Encord requires 'write' permissions to your cloud to re-encode videos.</Note>

Use the [dataset.re\_encode\_data()](/sdk-documentation/sdk-references/dataset#re-encode-data) method to re-encode a list of videos, replacing \<video1\_data\_hash> and \<video2\_data\_hash> below with the hashes of the videos to be re-encoded.

<CodeGroup>
  ```python Sample Code theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

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

  # Specify the dataset you want to re-encord data from by using its dataset hash
  dataset = user_client.get_dataset("<dataset_hash>")

  # Specify the data hashes of the files to be re-encoded
  task_id = dataset.re_encode_data(
      [
          "<video1_data_hash\>",
          "<video2_data_hash>",
      ]
  )

  # Print the task ID for the re-encoding job
  print(task_id)
  ```

  ```python Example output theme={"dark"}
  1337 
  ```
</CodeGroup>

The output is a list of task ID's of each re-encoding job. The `task_id` can be used to [monitor the progress](#check-the-status-of-a-re-encoding-task) of the task.

<Note>Ensure that the list contains videos from the same Dataset that was used to initialize the `EncordClient`. Any videos that do not belong to the Dataset used for initialization are ignored.</Note>

***

### Check the status of a re-encoding task

Use the [dataset.re\_encode\_data\_status()](/sdk-documentation/sdk-references/dataset#re-encode-data-status) method to get the status of an existing re-encoding task. Replace `task_id` in the sample below with the task ID of the re-encoding task you'd like to check the status of.

```python Sample Code theme={"dark"}
# Import dependencies
from encord import EncordUserClient

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

# Specify the dataset you want to re-encord data from by using its dataset hash
dataset = user_client.get_dataset("<dataset_hash>")

# Define and print the status of the re-encoding task by inserting the re-encoding task's ID
task = (
    dataset.re_encode_data_status("<task_id>")
)
print(task)
```

```python Example output theme={"dark"}
ReEncodeVideoTask(
    status="DONE",
    result=[
        ReEncodeVideoTaskResult(
            data_hash="<data_hash>",
            signed_url="<signed_url>",
            bucket_path="<bucket_path>",
        ),
        ...
    ]
) 
```

The ReEncodeVideoTask object contains a status field, which can take the following values:

* "SUBMITTED": the task is currently in progress and the status should be checked back again later.

* "DONE": the task has been completed successfully and the field ‘result’ would contain metadata about the re-encoded video.

* "ERROR": the task has failed and could not complete the re-encoding.

#### Re-encode locally

Some cases, such as corrupted metadata, might require you to re-encode your data locally before uploading them to the Encord platform.

Use the following `ffmpeg` command, replacing `video.mp4` with the name of the file you want to re-encode, and `re-encoded-video.mp4` with the name you want the re-encoded file to have:

```bash theme={"dark"}
ffmpeg -err_detect aggressive -fflags discardcorrupt -i video.mp4 -r 30 -c:v libx264 -movflags faststart -an -tune zerolatency re-encoded-video.mp4
```

<Warning>
  Since browsers require a constant frame rate, we apply the -r 30 flag (30 fps). Verify your video’s frame rate and adjust the value accordingly.
  We recommend using the average frame rate of your video to set the constant rate (rounded to the nearest whole number).

  You can figure out the average frame rate of your video with this command:

  ```bash theme={"dark"}
  ffprobe -v 0 -select_streams v:0 -show_entries stream=r_frame_rate -of default=noprint_wrappers=1:nokey=1 video.mp4 | bc -l
  ```

  You may need to install `ffprobe` & `bc`
</Warning>

<Note>
  Here is a summary of the various flags:

  * `-err_detect aggressive`: Improves error detection during decoding.
  * `-fflags discardcorrupt`: Discards corrupted packets to maintain integrity.
  * `-r 30`: This sets the frame rate to a constant 30 frames per second (FPS). Feel free to adjust `30` to your desired frame rate.
  * `-c:v libx264`: Specifies the `H.264` codec for video re-encoding.
  * `-movflags faststart`: Optimizes for web playback by moving video metadata to the beginning of the file.
  * -an: This ensures the audio is removed from the re-encoded video.
  * `-tune zerolatency`: Configures for low-latency encoding scenarios.
</Note>


# Remove Data from Datasets
Source: https://docs.encord.com/sdk-documentation/datasets-sdk/sdk-remove-data



<Note>While it's possible to delete data from a Dataset, entire Datasets can't be deleted using the SDK. Use the Encord platform to delete Dataset. </Note>

Use the [dataset.delete\_data()](/sdk-documentation/sdk-references/dataset#delete-data) method to delete from Datasets.

In the script below, replace \<video1\_data\_hash> and \<image\_group1\_data\_hash> with the hashes for the  data units you want to remove from a Dataset. If the   data unit being removed is saved on Encord-hosted storage, the file will be deleted.

```python theme={"dark"}
# Import dependencies
from encord import EncordUserClient

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

# Specify the Dataset you want to remove files from. Replace \<dataset_hash> with the hash of your Dataset
dataset = user_client.get_dataset(
    "<dataset_hash>"
    )

# Specify the files to be deleted. Include all the data hashes below
dataset.delete_data(
    [
        "<video1_data_hash\>",
        "<image_group1_data_hash>",
    ]
)
```


# Verify Where Files are Stored (Dataset)
Source: https://docs.encord.com/sdk-documentation/datasets-sdk/sdk-view-dataset-files



The following script prints the storage locations of all files in a Dataset. This includes the cloud storage locations for private cloud data, and Encord storage location for local data in the Dataset. Knowing where your files are storage helps to cross-verify that all data from a cloud bucket has been added to a Dataset.

<Note>To learn how to view the storage locations of all files in a Project, see our documentation [here](/sdk-documentation/projects-sdk/projects-and-workflows/sdk-view-project-files). </Note>

In the following script, ensure that you:

* Replace \<private\_key\_path> with the path to your private key.
* Replace \<dataset\_hash> with the hash of the Dataset you want to know the storage locations for.

<CodeGroup>
  ```python Sample Code theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient, Project,Dataset
  from encord.objects.project import ProjectDataset
  from encord.orm.dataset import DatasetAccessSettings

  # Instantiate client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Print URLs of all files in the Dataset
  dataset_level_file_links = []
  dataset: Dataset = user_client.get_dataset("<dataset_hash>")
  for data in dataset.list_data_rows():
      dataset_level_file_links.append(data.file_link)
  print(dataset_level_file_links)
  ```

  ```Example Output theme={"dark"}
  ['https/my-aws-bucket/iaDJxNNrMuQMtFPcP9oszw2OCHm2/0f31636f-54cc-4f8f-b556-baba47bfbda1', 'https/my-aws-bucket/iaDJxNNrMuQMtFPcP9oszw2OCHm2/9c202a5a-7c79-4a95-91ef-37adcb331d92']
  ```
</CodeGroup>


# De-identifying DICOM Files
Source: https://docs.encord.com/sdk-documentation/dicom-sdk/sdk-deidentify-dicom



DICOM files may contain sensitive and personally identifiable information (PII) about patients, including their name, date of birth, medical record number. In these cases it is essential to anonymize each file, to protect patient privacy and comply with legal and ethical regulations related to healthcare data.

<Warning>This is a premium feature and running it incurs additional costs. Contact us at [support@encord.com](mailto:support@encord.com) to learn about pricing.</Warning>

In this tutorial you will learn how to anonymize / de-identify DICOM files in two steps:

1. [Setting up the de-identification function](#set-up-the-de-identification-function).
2. [Using the de-identification function](#de-identifying).

Finally, you will learn how to [interpret the JSON output](#output) of the de-identification process.

<Note>Redacted tag values are completely removed.</Note>

## Set up the de-identification function

Adjust the de-identification function [found here](/sdk-documentation/sdk-references/user_client#deidentify_dicom_files) to suit your needs.

## De-identifying

The Python code below is used to add criteria and call the de-identification function.

<Tip> An SSH public / private key pair is required to use the sample script below. To learn how to generate one, see our documentation [here](/platform-documentation/General/general-access-keys).</Tip>

<Tip> Make sure to edit the `criteria` used to evaluate each file to suit your needs - any number of criteria can be used.</Tip>

```python theme={"dark"}

import multiprocessing
import time
from pathlib import Path
from typing import List
import glob
import os
from encord import EncordUserClient
from encord.objects.common import (
    DeidentifyRedactTextMode,
    SaveDeidentifiedDicomConditionNotSubstr,
    SaveDeidentifiedDicomConditionIn
)

# Replace s3://EXAMPLE-BUCKET/raw/ with the path to the file storage you're using 
def filelist_helper(dir,prefix='s3://EXAMPLE-BUCKET/raw/'):
    fl = [prefix+os.path.basename(f) for f in glob.glob(dir+"*.dcm")]
    return fl

# Add criteria to evaluate each file. See the 'Setting evaluation criteria' section below for more info. 
criteria = [
    SaveDeidentifiedDicomConditionNotSubstr("PRIMARY","ImageType"),              
    SaveDeidentifiedDicomConditionIn(["ct","pt","nm","mr","mg","pt"],"Modality") 
]

def deidentify(
    integration_title: str,
    dicom_urls: List[str],
) -> List[str]:

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

    integration_hash = None

    # Find integration_hash for requested integration_title
    for integration in user_client.get_cloud_integrations():
        if integration.title == integration_title:
            integration_hash = integration.id

    if not integration_hash:
        raise Exception(f"Integration with integration_title={integration_title} not found")

    deidentified_dicom_urls = []

    # 'dicom_urls' should be a a single list containing the URLs of all instances of a series to be de-identified. Splitting a series into multiple lists might lead to inaccurate results and is therefore not recommended
    deidentified_dicom_url = user_client.deidentify_dicom_files(
        dicom_urls=dicom_urls,
        integration_hash=integration_hash,
        redact_dicom_tags = True,
        redact_pixels_mode = DeidentifyRedactTextMode.REDACT_ALL_TEXT,
        save_conditions = criteria,
        upload_dir = "s3://EXAMPLE-BUCKETt/output"
    )
    print(f"Deidentified url: {deidentified_dicom_url}")
    deidentified_dicom_urls += deidentified_dicom_url

    return deidentified_dicom_urls

# Replace MY-ENCORD-INTEGRATION with the title of your private cloud integration
_integration_title = "MY-ENCORD-INTEGRATION"

_deidentified_dicom_urls = deidentify(
    _integration_title,
    _dicom_urls,
)

```

### Setting evaluation criteria

Evaluation criteria are conditions that determine whether a file will be de-identified or not. Criteria can take many forms, but will always return either 'true' or 'false'.

<Note>All strings and inputs into the criteria functions are case-insensitive.</Note>

There are two distinct criteria functions:

* "SaveDeidentifiedDicomConditionNotSubstr" will return 'true' if the first argument (PRIMARY in the example above), is not contained in the second argument (ImageType in the example above). In plain English, the example above checks whether the file's ImageType doesn't contain the word 'Primary', and returns 'true' if this condition is fulfilled.

* "SaveDeidentifiedDicomConditionIn" will return 'true' if the first argument (\["ct","pt","nm","mr","mg","pt"] in the example above) is contained in the second argument Modality. In plain English, the example above checks whether any of the strings contained in the list are contained within the file's Modality. If any one of them is, the function returns 'true'.

## Output

This section will explain the output of the de-identification function. Click the dropdown below to see a sample output file

<AccordionGroup>
  <Accordion title=" Sample JSON ">
    ```json theme={"dark"}
    {
    "url": "s3://EXAMPLE-BUCKETt/raw/should_fail_1.2.840.113619.2.283.6945.3146400.16119.1391477777.833.dcm",
    "StudyInstanceUID": "1.2.840.113619.6.283.4.679947340.8065.1391798290.307",
    "StudyInstanceUID_deid": "1.2.840.113619.6.283.4.679947340.8065.1391798290.307",
    "SeriesInstanceUID": "1.2.840.113619.2.283.6945.3146400.21673.1391477673.97",
    "SeriesInstanceUID_deid": "1.2.840.113619.2.283.6945.3146400.21673.1391477673.97",
    "save_conditions_evaluations":
    [
        {
            "condition":
            {
                "value": "PRIMARY",
                "condition_type": "NOT_SUBSTR",
                "dicom_tag": "ImageType"
            },
            "tag_value": "DEMOGRAPHICDATA",
            "evaluated_value": false
        },
        {
            "condition":
            {
                "value":
                [
                    "ct",
                    "pt",
                    "nm",
                    "mr",
                    "xr",
                    "mg"
                ],
                "condition_type": "IN",
                "dicom_tag": "Modality"
            },
            "tag_value": "MR",
            "evaluated_value": true
        }
    ],
    "save_condition": false,
    "save_condition_series_agg": false,
    "save_disabling_urls_series_agg":
    [
        "s3://EXAMPLE-BUCKETt/raw/should_fail_1.2.840.113619.2.283.6945.3146400.16119.1391477777.833.dcm"
    ],
    "url_deid": "s3://EXAMPLE-BUCKETt/Pixel-redaction-ready/deid_169089614143326592_should_fail_1.2.840.113619.2.283.6945.3146400.16119.1391477777.833.dcm"
    }
    ```
  </Accordion>
</AccordionGroup>

| **Key**                          | **Description**                                                      | **Notes**                                                                                                                              |
| -------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                            | A URL to the DICOM file                                              |                                                                                                                                        |
| `StudyInstanceUID`               | The study's ID                                                       |                                                                                                                                        |
| `StudyInstanceUID_deid`          | A converted version of the study's ID used by Encord                 | Identical to `StudyInstanceUID`, unless `StudyInstanceUID` was invalid                                                                 |
| `SeriesInstanceUID`              | The series' ID                                                       |                                                                                                                                        |
| `SeriesInstanceUID_deid`         | A converted version of the series' ID used by Encord                 | Identical to `SeriesInstanceUID`, unless `SeriesInstanceUID` was invalid                                                               |
| `save_conditions_evaluations`    | Contains a list of conditions                                        | These need to be met in order for a file to be de-identified                                                                           |
| `condition`                      | Contains a given condition's details                                 | A `condition` is satisfied when the `value` fulfills the `condition_type`                                                              |
| `value`                          | The elements being evaluated by the `condition_type`                 | Can be thought of as the 'answer' to a `condition`                                                                                     |
| `condition_type`                 | The type of condition being evaluated                                | Can be thought of as the 'question' to a `condition`                                                                                   |
| `dicom_tag`                      | The DICOM tag on which a condition is being evaluated                |                                                                                                                                        |
| `save_condition`                 | Does the condition have to be `true` or `false` for the file to pass |                                                                                                                                        |
| `save_condition_series_agg`      | The series as a whole evaluated as `true` or `false`                 | For this to be `true` **all** `save_condition`s need to be `true` For this to be `false` **all** `save_conditions`s need to be `false` |
| `save_disabling_urls_series_agg` | A list of files which did not meet the required `save_condition`     | Only relevant if the series didn't pass                                                                                                |
| `url_deid`                       | The URL of the new, de-identified file.                              |                                                                                                                                        |


# SDK DICOM Basics
Source: https://docs.encord.com/sdk-documentation/dicom-sdk/sdk-dicom-basics



This page outlines the basic principles of using the Encord SDK to work with DICOM files.

## Getting started

1. Make sure you have installed all prerequisites and the Encord SDK. If you haven't done so, all the instructions you need to do so are [here](/sdk-documentation/getting-started-sdk/installation-sdk).

2. Ensure you have a public - private key pair to authenticate with Encord. To learn more about authentication in Encord see our documentation [here](/sdk-documentation/general-sdk/authentication-sdk).

<Tip>You can find instructions on creating a public-private key pair in the Encord platform [here](/platform-documentation/General/general-access-keys). </Tip>

## Common entities used when working with DICOM

The following table shows how to refer to various DICOM-related entities when using the Encord SDK.

| **Entity**        | **Name in the SDK**  | **Notes**                                                                                                                                                                                                                                        |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Dataset           | `dataset_hash`       | Corresponds to the Dataset ID.                                                                                                                                                                                                                   |
| Data Unit         | `data_hash`          | Corresponds to the data unit's ID.                                                                                                                                                                                                               |
| Project           | `project_hash`       | Corresponds to the Project's ID.                                                                                                                                                                                                                 |
| Ontology          | `ontology_hash`      | Corresponds to the Ontology's ID. Learn how to work with Ontologies [here](/sdk-documentation/ontologies-sdk/ontologies).                                                                                                                        |
| Study ID          | `study_uid`          | Corresponds to the [Study ID as defined in the DICOM standard](https://dicom.innolitics.com/ciods/mr-image/general-study/0020000d). Learn how to work with DICOM metadata [here](/sdk-documentation/dicom-sdk/sdk-dicom-metadata).               |
| Series ID         | `series_uid`         | Corresponds to the [Series ID as defined in the DICOM standard](https://dicom.innolitics.com/ciods/mr-image/general-series/00081250/0020000e). Learn how to work with DICOM metadata [here](/sdk-documentation/dicom-sdk/sdk-dicom-metadata).    |
| Patient ID        | `patient_id`         | Corresponds to the [Patient ID as defined in the DICOM standard](https://dicom.innolitics.com/ciods/rt-plan/patient/00101002/00100020). Learn how to work with DICOM metadata [here](/sdk-documentation/dicom-sdk/sdk-dicom-metadata).           |
| DICOM Instance ID | `dicom_instance_uid` | Corresponds to the [DICOM Instance ID as defined in the DICOM standard](https://dicom.innolitics.com/ciods/rt-structure-set/sop-common/00080018). Learn how to work with DICOM metadata [here](/sdk-documentation/dicom-sdk/sdk-dicom-metadata). |
| Frame Width       | `width`              | Corresponds to the [columns attribute as defined in the DICOM standard](https://dicom.innolitics.com/ciods/rt-dose/image-pixel/00280011). Learn how to work with DICOM metadata [here](/sdk-documentation/dicom-sdk/sdk-dicom-metadata).         |
| Frame Height      | `height`             | Corresponds to the [rows attribute as defined in the DICOM standard](https://dicom.innolitics.com/ciods/rt-dose/general-image/00880200/00280010). Learn how to work with DICOM metadata [here](/sdk-documentation/dicom-sdk/sdk-dicom-metadata). |

<Tip> The hash for any entity can be seen and copied by selecting the entity in the Encord platform, as shown below for an ontology. </Tip>

> <img />

## DICOM metadata

Please see our [tutorial on DICOM metadata](/sdk-documentation/dicom-sdk/sdk-dicom-metadata) to learn how to view metadata pertaining to a series, or individual slices.

## Uploading DICOM data to Encord

To upload DICOM data to Encord:

1. [Create a dataset](/sdk-documentation/datasets-sdk/sdk-create-and-view-datasets).
2. Upload data from [your local machine](/sdk-documentation/index-sdk/sdk-upload-data#upload-local-data-to-an-existing-folder), or register data [from private cloud storage](/sdk-documentation/getting-started-sdk/sdk-register-data-aws).

<Note>To add data from a cloud server, a JSON file specifying the files to be added is required. [Click here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) to learn more.</Note>

<Tip>You can also use the Encord platform to [create a dataset, and add data to the dataset](/platform-documentation/Annotate/annotate-datasets/annotate-datasets).</Tip>


# Reading DICOM Metadata
Source: https://docs.encord.com/sdk-documentation/dicom-sdk/sdk-dicom-metadata



<Note>DICOM metadata is distinct from `clientMetadata`, which is the metadata associated with individual data units. See our [tutorial on `clientMetadata`](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata) for more information.</Note>

DICOM related metadata is accessed by specifying the dataset using the \<project\_hash>. It contains the patient ID, series ID, and study ID that link the unlabeled DICOM data to the labeled data that is [exported from Encord](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels).

## Reading series metadata

The following code reads and prints the [patient ID](https://dicom.innolitics.com/ciods/rt-plan/patient/00101002/00100020) (`patient_id`), [series ID](https://dicom.innolitics.com/ciods/mr-image/general-series/00081250/0020000e) (`series_uid`) and [study ID](https://dicom.innolitics.com/ciods/mr-image/general-study/0020000d) (`study_uid`) of all label rows in the specified Project.

<CodeGroup>
  ```python theme={"dark"}

  #Import dependencies
  from encord import EncordUserClient

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

  # Specify the project for which you want to read the patient and series IDs
  project = client.get_project("<project_hash>")

  # Fetch the label and frame information for this project
  label_rows = project.list_label_rows_v2()

  for label_row in label_rows:
      # Initialize labels
      label_row.initialise_labels()
      # Print Patient ID, Series ID, and Study ID
      print (label_row.metadata)
  ```

  ```python Output theme={"dark"}
  patient_id='example_fmri_140207' study_uid='1.2.840.113619.6.283.47340.8065.13236498290.27' series_uid='1.2.840.113619.2.28.3100000.21673.1390073.97'
  ```
</CodeGroup>

***

## Reading frame metadata

The following code reads and prints frame specific DICOM metadata including the [DICOM instance ID](https://dicom.innolitics.com/ciods/rt-structure-set/sop-common/00080018) (`dicom_instance_uid`), the multiframe frame number (`multiframe_frame_number`), the file URI (`file_uri`) and the [height](https://dicom.innolitics.com/ciods/rt-dose/general-image/00880200/00280010) as well as [width of the frame](https://dicom.innolitics.com/ciods/rt-dose/image-pixel/00280011), as can be seen in the sample output provided.

<CodeGroup>
  ```python theme={"dark"}

  #Import dependencies
  from encord import EncordUserClient

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

  # Specify the project for which you want to read the patient and series IDs
  project = client.get_project("<project_hash>")

  # Fetch the label and frame information for this project
  label_rows = project.list_label_rows_v2()

  for label_row in label_rows:
      # Initialize labels
      label_row.initialise_labels()
      
      # Print Frame specific DICOM metadata
      for v in label_row.get_frame_views():
          print(v.metadata)

  ```

  ```python Output theme={"dark"}
  dicom_instance_uid='1.5.740.183619.283.6905.311000.16119.13000477777.716' multiframe_frame_number=None file_uri='my-storage-location/iaDJxNNrMubabutFPcP9oszw2shmeHm2/5e8880c2-9177-4cf6-b298-ebd3d1d31eb8' width=256 height=256
  ```
</CodeGroup>

## Reading frame dimensions

Use the script below to obtain the dimensions for a given slice or frame.

<Warning>Width and height fields other than those printed by this script may be present in the metadata. These refer to the DICOM series' dimensions (the maximum width and height of the series) and will not be applicable to all slices or frames.</Warning>

<CodeGroup>
  ```python Sample Code theme={"dark"}

  #Import dependencies
  from encord import EncordUserClient

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

  # Specify the project for which you want to read the patient and series IDs
  project = client.get_project("<project_hash>")

  # Fetch the label and frame information for this project
  label_rows = project.list_label_rows_v2()

  for label_row in label_rows:
      # Initialize labels
      label_row.initialise_labels()

      for v in label_row.get_frame_views():
          print(f"frame width: {v.metadata.width}, height: {v.metadata.height}")

  ```

  ```python Example Output theme={"dark"}
  series width: 1381, height: 1982
  frame width: 1381, height: 1982
  frame metadata width: 934, height: 1982
  frame width: 1381, height: 1982
  frame metadata width: 1381, height: 1632
  ```
</CodeGroup>


# 2. Authentication Basics
Source: https://docs.encord.com/sdk-documentation/general-sdk/authentication-sdk



To authenticate with Encord you must register a public key in the Encord platform. See [our documentation here](/platform-documentation/General/general-access-keys) to learn more. Users can only access Projects, Datasets, and Ontologies from within their [Workspace](/platform-documentation/General/general-workspace-settings).

<Info>Authentication must occur every time an SDK script is run.</Info>

<Info>Ensure your private key is not password protected. All private keys generated on the Encord platform as described in [our documentation](/platform-documentation/General/general-access-keys) are not password protected by default.</Info>

After registering a public key, use the corresponding private key to authenticate your [EncordUserClient](/sdk-documentation/sdk-references/user_client). The following code sample needs to be included in all SDK interactions, and hence is included in all code snippets we provide in these tutorials.

<Tip>We recommend using the file path to your private key, rather than the private key itself when authenticating.</Tip>

The following script must be added to all Encord SDK scripts. It is present in all complete code examples we provide.

<CodeGroup>
  ```python Template theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

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

  ```python Example Global theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

  # Authenticate with Encord using the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="/Users/chris-encord/sdk-ssh-private-key"
      )

  ```
</CodeGroup>

## US Customers

If you are using Encord's US based hosted platform, ALL authentication for the SDK MUST include the following:

```python theme={"dark"}
domain="https://api.us.encord.com"
```

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

  # Authenticate with Encord 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",
  )
  ```

  ```python Example US Domain theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

  # Authenticate with Encord using the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="/Users/chris-encord/sdk-ssh-private-key",
      domain="https://api.us.encord.com",
      )

  ```
</CodeGroup>


# Entities and Relationships
Source: https://docs.encord.com/sdk-documentation/general-sdk/general-concepts-sdk



The Annotate SDK revolves around three major concepts: Projects, Datasets, and Ontologies. Each of these concepts is linked to a `class` that allows you to interact with them using the Annotate SDK. For example, the *Project* has an associated [Project](/sdk-documentation/sdk-references/project#project) class and the *Dataset* has an associated [Dataset](/sdk-documentation/sdk-references/dataset) class.

<Note>Install the Annotate SDK by following the [Installation](/sdk-documentation/getting-started-sdk/installation-sdk) guide or go to the [Authentication](/sdk-documentation/general-sdk/authentication-sdk) page to get started with the Encord Annotate SDK.</Note>

## Entity Relationships

The following diagram shows how entities in Encord are organized.

```mermaid theme={"dark"}
erDiagram
    Project {
        string project_hash
    }
    DataUnit {
        string data_hash
        string data_title
        string client_metadata
    }
    Dataset {
        string dataset_hash
        string dataset_title
    }
    Ontology {
        string ontology_hash
        string ontology_name
        string ontology_description
    }
    Workflow {
        string workflow_hash
    }
    Collaborator {
        string user
    }

    Project ||--o| Dataset : "attaches"
    Project ||--o| Ontology : "attaches"
    Project ||--o| Workflow : "follows"
    Project ||--o{ Collaborator : "includes"
    Dataset ||--o{ DataUnit : "composed of"
```

## SDK Data Structure

The following diagram shows how data in the Encord SDK is structured for each labeled Data Unit.

<div>
  ```mermaid theme={"dark"}
  erDiagram
      LabelRow {
          string label_hash
          string data_unit_hash
          string status
      }
      Branch {
          string branch_name
          string user
      }
      Labels {
          string objectHash
          string classificationHash
          string label_type
      }

      LabelRow ||--o{ Branch : "can have multiple"
      Branch ||--o{ Labels : "contains multiple"
  ```
</div>

***

## Users

Users are people authenticated to interact with the Encord platform. Users can access resources and capabilities that are also available on the platform.

<Tip>For collaborative teams using our SDK, we recommend creating shared service accounts and creating access keys for those shared accounts. For example, to have several people create ontologies, datasets, and projects programmatically, create an email account for use with Encord (for example, [encord-admins@mycompany.com](mailto:encord-admins@mycompany.com)) and generate an SSH for that email account.</Tip>

***

## Projects

The space where labels, annotations, and reviews live.
Projects can be linked to multiple datasets. For a Web-app specific introduction,
go to the [Projects](/platform-documentation/GettingStarted/gettingstarted-create-project) page.

<div>
  <img />
</div>

***

## Datasets

Datasets are subsets of data you upload to Encord. Datasets are attached to, and can be reused across multiple Projects.

Learn more about Datasets in Encord [here](/platform-documentation/Annotate/annotate-datasets/annotate-datasets).

Each Dataset is identified using a unique `"<dataset_hash>"` - a unique ID that can be found within the dataset's *Settings*, or the URL in the Encord platform when the dataset is being viewed, as shown below.

<div>
  <img />
</div>

### Data units

Datasets are composed of data units - packages of data that constitute a single annotation task. For example, a video, a single image, an image group, or a DICOM series. Data units are identified using their `<data_hash>`, which is found in the URL when the data unit is open in your browser, as shown below.

`app.encord.com/label_editor/\<data_hash>&\<project_hash>/0/0` or `app.us.encord.com/label_editor/\<data_hash>&\<project_hash>/0/0`

<Note>The `<data_unit_hash>` and the `<project_hash>` are both shown in the URl when a data unit is open in the browser. They are separated by the '&' symbol.</Note>

***

## Label Row

Label Rows are collections of labels belonging to a particular data unit in a Project.

***

## Branches

All labels are created on a branch. In **Consensus Projects**, each annotator works on their own separate branch to create labels. In **Non-Consensus Projects**, all labels are created on the `main` branch.

Learn more about Consensus Projects [here](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus).

***

## Ontology

Ontologies are hierarchical structures that define the top-level concepts and categories in your data, along with nested attributes for detailed annotations. They consist of *Classes* at the top level, which can be either *Objects* or *Classifications*.

Learn more about Ontologies [here](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies).


# Network Configurations
Source: https://docs.encord.com/sdk-documentation/general-sdk/network-configurations-sdk



If you have an unstable connection, sometimes you might want to overwrite the defaults of the `RequestsSettings`. These settings propagate to the Project and Dataset objects that are created from the [EncordUserClient](/sdk-documentation/sdk-references/user_client).

You can overwrite the timeouts for read and write operations. The following script overwrites the read, write, and connect timeouts. Ensure that you replace 'private\_key\_path' with the full path to your private key.

```python theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.http.constants import RequestsSettings

# Replace the number 300 with the number of seconds you want to set the timeout to
NEW_TIMEOUT = 300

request_settings = RequestsSettings(
    connect_timeout=NEW_TIMEOUT,
    read_timeout=NEW_TIMEOUT,
    write_timeout=NEW_TIMEOUT,
)

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


# Bulk Action Best Practices
Source: https://docs.encord.com/sdk-documentation/general-sdk/sdk-bulk-action-best-practices



When trying to perform certain actions at scale, we recommend using the [bundle](/sdk-documentation/sdk-references/http.bundle) function to significantly improve the performance of the action.

<Tip>
  We recommend using [`bundle`](/sdk-documentation/sdk-references/http.bundle#bundle-objects) in your scripts to improve performance. Keep bundle sizes under 1000 operations. Bundles of more than 1000 operations can degrade performance rather than improve performance.

  The optimal bundle size depends on your use case. For example, for videos with a large number of labels, start with 20 operations and adjust up or down based on performance.
</Tip>

How and when [bundle](/sdk-documentation/sdk-references/http.bundle) is used depends on what you are trying to do.
Here are some specific examples of using bundles to improve performance:

<div lang="en">
  <head>
    <meta />

    <meta name="viewport" />

    <title>Clickable Div</title>
  </head>

  <div>
    <a href="/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual#import-labels-in-bulk">
      Bulk Label Import
    </a>

    <a href="/sdk-documentation/sdk-labels/sdk-export#bulk-export-labels">
      Bulk Label Export
    </a>

    <a href="/sdk-documentation/projects-sdk/sdk-workflows-stages">
      Project Workflows
    </a>
  </div>
</div>


# Workspace-Wide Actions
Source: https://docs.encord.com/sdk-documentation/general-sdk/sdk-org-actions



Workspace-wide actions can be performed by Workspace Admins and Service Accounts with Admin access, allowing them to list and modify all Datasets, Ontologies, and Projects within a Workspace.

A common use case is creating a Service Account with managerial privileges, enabling it to perform key administrative tasks on behalf of the Workspace Admin.

<Warning>
  Projects, Datasets, and Ontologies cannot be deleted using the SDK. To remove them, use the Encord platform.
</Warning>

***

## Listing Datasets

The following script can be used by users and Service Accounts with the Admin role in their Workspace to retrieve a list of all Datasets.

```python theme={"dark"}
# 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>"
    )

print (user_client.get_datasets(include_org_access=True))
```

***

## List Ontologies

The following script can be used by users and Service Accounts with the Admin role in their Workspace to retrieve a list of all Ontologies.

```python theme={"dark"}
# 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>"
    )

print (user_client.get_ontologies(include_org_access=True))
```

***

## List Projects

The following script can be used by users and Service Accounts with the Admin role in their Workspace to retrieve a list of all Projects.

```python theme={"dark"}
# 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>"
    )

print (user_client.list_projects(include_org_access=True))
```

***

## List Cloud Integrations

The following script can be used by users and Service Accounts with the Admin role in their Workspace to retrieve a list of all Cloud Integrations.

```python theme={"dark"}
# 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>"
    )

print (user_client.get_cloud_integrations(include_org_access=True))
```

***

## List Storage Folders

The following scripts can be used by users and Service Accounts to list folders belonging to your Workspace.

<CodeGroup>
  ```python Top Level Folders theme={"dark"}
  # 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>"
      )

  print (user_client.list_storage_folders(include_org_access=True))
  ```

  ```python All Folders in Storage theme={"dark"}
  # 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>"
      )

  print (user_client.find_storage_folders(include_org_access=True))
  ```
</CodeGroup>

## List Files

The following script can be used by users and Service Accounts to find all files belonging to your Workspace.

```python All Files theme={"dark"}
# 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>"
    )

print (user_client.find_storage_items(include_org_access=True))
```


# SDK Quick Peek
Source: https://docs.encord.com/sdk-documentation/general-sdk/sdk-quick-lookup



## 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:

```python theme={"dark"}
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:

```python theme={"dark"}
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")`
* Add a skeleton object + template together (keeps their `feature_node_hash` in sync automatically):

```python theme={"dark"}
skeleton_object, skeleton_template = ontology_structure.add_skeleton_object(
    name="Pose", skeleton_template=my_skeleton_template
)
```

## Datasets

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

```python theme={"dark"}
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:

```python theme={"dark"}
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:

```python theme={"dark"}
stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)
for task in stage.get_tasks()
```

* Move tasks in non-Consensus Projects:

```python theme={"dark"}
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:

```python theme={"dark"}
for task in stage.get_tasks(data_hash=data_hashes):
    task.assign("chris@acme.com")
    task.reject(bundle=bundle)
```

* Approve tasks:

```python theme={"dark"}
for task in stage.get_tasks(data_hash=data_hashes):
    task.assign("chris@acme.com")
    task.approve(bundle=bundle)
```

* Add Taskers to Project:

```python theme={"dark"}
added_users = project.add_users(
    ["example1@encord.com", "example2@encord.com"],
    ProjectUserRole.ANNOTATOR,
)
```

* Add issues to tasks:

```python theme={"dark"}
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:

```python theme={"dark"}
# 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

```python theme={"dark"}
# 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):

```python theme={"dark"}
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):

```python theme={"dark"}
 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)

```python theme={"dark"}
polygon_object_instance.set_for_frames(
    coordinates=PolygonCoordinates(polygons=polygons),
    frames=0,
    manual_annotation=True,
    confidence=1.0,
    )
```

* Import labels (Polyline)

```python theme={"dark"}
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)

```python theme={"dark"}
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)

```python theme={"dark"}
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)

```python theme={"dark"}
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)

```python theme={"dark"}
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)

```python theme={"dark"}
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:

```python theme={"dark"}
for g in groups:
    group = folder.create_data_group(
        DataGroupGrid(
            name=g["name"],
            layout_contents=g["uuids"],
        )
    )
```

## Collections

* Create Index pre-filter

```python theme={"dark"}
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:

```python theme={"dark"}
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.")`


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



[User groups](/platform-documentation/General/general-workspace-settings#user-groups) support adding or removing users in bulk from Projects, Datasets, and Ontologies within your Workspace.

This page covers the full group workflow with the SDK: managing your organization's members, creating and managing groups, managing group membership, and assigning users and groups to resources.

<Info>
  All examples authenticate with an SSH private key — replace `<private_key_path>` with the path to your key. See [Authentication](/sdk-documentation/general-sdk/authentication-sdk). US platform users should add `domain="https://api.us.encord.com"` to `create_with_ssh_private_key`.
</Info>

## Organization members

Before a user can be added to a group, they must be a member of your organization. Use these `EncordUserClient` methods to manage organization membership. Managing members requires organization admin permissions.

| Role (`role_mnemonic_name`) | Description                                                        |
| --------------------------- | ------------------------------------------------------------------ |
| `ADMIN`                     | Full administrative access. Only `internal` members can be admins. |
| `MEMBER`                    | Standard member.                                                   |
| `WORKFORCE_MANAGER`         | Manages the annotation workforce.                                  |
| `TASKER`                    | Annotator / task worker.                                           |

`member_type` is either `"internal"` (a member of your organization) or `"external"` (a collaborator, e.g. from another company).

```python Manage organization members theme={"dark"}
# 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>"
    )

# --- List organization members ---
for member in user_client.list_organisation_users():
    print(f"{member.email} | role: {member.role_mnemonic_name} | type: {member.member_type}")

# --- Add a member ---
# role_mnemonic_name and member_type are keyword-only.
# If the email has no Encord account, one is created and an onboarding email is sent.
user_client.add_organisation_user(
    "new.member@example.com",
    role_mnemonic_name="MEMBER",
    member_type="internal",
)

# --- Remove a member ---
# Membership is deleted immediately; resource unassignment is scheduled.
user_client.remove_organisation_user("former.member@example.com")
```

## Create and manage groups

You can create and manage user groups directly with the SDK. The calling user is automatically added as a manager of any group they create.

<Note>
  You can also [create user groups](/platform-documentation/General/general-workspace-settings#create-user-groups) in the Encord platform.
</Note>

```python Create and manage a group theme={"dark"}
# 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>")
```

## Manage group membership

Add and remove the users that belong to a group. All emails must already belong to members of your organization (see [Organization members](#organization-members)).

```python Manage group membership theme={"dark"}
# 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>"
    )

# Get the group you want to manage
group = user_client.get_group("<group_hash>")

# --- Add members ---
group.add_users(["reviewer1@example.com", "reviewer2@example.com"])

# --- List members ---
for user in group.list_users():
    print(user.email)

# --- Remove members ---
group.remove_users(["reviewer2@example.com"])
```

## List user groups

Listing user groups returns a list of all user group names.

### List all user groups in your Workspace

You can list all users groups that currently exist within your Workspace.

In the following script, ensure that you replace \<private\_key\_path> with the path to your private key.

```python theme={"dark"}
# 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 private key.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# List all groups for the Workspace your user belongs to
user_client.list_groups()

```

### List user groups for Projects / Datasets / Ontologies

You can list all existing user groups for a specific Project. In the following script, ensure that you:

* Replace \<private\_key\_path> with the path to your private key.
* If you are using the Project script, replace \<project\_hash> with the hash of the Project you want to list user groups for.
* If you are using the Dataset script, replace \<dataset\_hash> with the hash of the Dataset you want to list user groups for.
* If you are using the Ontology script, replace \<ontology\_hash> with the hash of the Ontology you want to list user groups for.

<CodeGroup>
  ```python Project theme={"dark"}
  # Import dependencies
  from encord.user_client 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>"
      )

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

  # List Project Groups
  for project_group in project.list_groups():
      print(project_group)
  ```

  ```python Dataset theme={"dark"}
  # Import dependencies
  from encord.user_client 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>"
      )

  # Specify the Dataset. Replace <dataset_hash> with the hash for your Dataset
  dataset = user_client.get_dataset("<dataset_hash>")

  # List Dataset Groups
  for dataset_group in dataset.list_groups():
      print(dataset_group)
  ```

  ```python Ontology theme={"dark"}
  # Import dependencies
  from encord.user_client 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>"
      )

  # Specify the Ontology. Replace <ontology_hash> with the hash for your Ontology
  ontology = user_client.get_ontology("<ontology_hash>")

  # List Dataset Groups
  for ontology_group in ontology.list_groups():
      print(ontology_group)
  ```

  ```Example output theme={"dark"}
  group_hash=UUID('fd299110-b10b-42c0-b014-8ffecb44ca6b') name='Annotators1' description='annotator_team_1' created_at=datetime.datetime(2022, 10, 28, 10, 1, 44, 664227)
  group_hash=UUID('fe8ac5dc-6ac4-489c-a034-917752c341a4') name='Annotators2' description='annotator_team_2' created_at=datetime.datetime(2022, 10, 19, 16, 56, 13, 832372)
  ```
</CodeGroup>

## Assign users directly to Projects / Datasets

As well as adding whole groups, you can add individual users to a Project or Dataset and set the role they hold there. Adding a user who already has access leaves their existing role unchanged.

### Projects

`ProjectUserRole` supports read-only viewers via `VIEWER`:

| `ProjectUserRole`    | Description               |
| -------------------- | ------------------------- |
| `ADMIN`              | Full project access.      |
| `ANNOTATOR`          | Can annotate.             |
| `REVIEWER`           | Can review.               |
| `ANNOTATOR_REVIEWER` | Can annotate and review.  |
| `TEAM_MANAGER`       | Manages the project team. |
| `VIEWER`             | Read-only access.         |

```python Manage project users theme={"dark"}
# Import dependencies
from encord import EncordUserClient, Project
from encord.utilities.project_user import ProjectUserRole

# 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. Replace <project_hash> with the hash for your Project
project: Project = user_client.get_project("<project_hash>")

# --- Add users with a role ---
added = project.add_users(
    ["annotator@example.com", "observer@example.com"],
    ProjectUserRole.ANNOTATOR,
)
for user in added:
    print(user.user_email, user.user_role)

# --- Add a read-only viewer ---
project.add_users(["stakeholder@example.com"], ProjectUserRole.VIEWER)

# --- List users ---
for user in project.list_users():
    print(user.user_email, user.user_role)

# --- Remove users ---
project.remove_users(["observer@example.com"])
```

### Datasets

`DatasetUserRole` is either `ADMIN` or `USER`.

```python Manage dataset users theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.orm.dataset import DatasetUserRole

# 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 Dataset. Replace <dataset_hash> with the hash for your Dataset
dataset = user_client.get_dataset("<dataset_hash>")

# --- Add, list, and remove users ---
dataset.add_users(["curator@example.com"], DatasetUserRole.USER)
for user in dataset.list_users():
    print(user.user_email, user.user_role)
dataset.remove_users(["curator@example.com"])
```

## Add user groups

User groups can be added to Projects, Datasets, and Ontologies.

### Add user group to Projects

Use the following scripts to add user groups to a Project.

<Note>
  Only group members are added, not group managers.
</Note>

In the following scripts, ensure that you:

* Replace \<private\_key\_path> with the path to your private key.
* Replace \<project\_hash> with the hash of the Project you want to add a user group to.
* Replace \<group\_name1> and \<group\_name2> with the name of the user group(s) you want to add to the Project. You can add one or multiple groups to a Project at once.

The different tabs show how to assign different user roles to the user group being added.

<CodeGroup>
  ```python Admin theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.utilities.project_user import ProjectUserRole

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

  # Add group to Project. Replace <project_hash> with the hash of the Project
  project = user_client.get_project("<project_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  project.add_group(group_hashes, ProjectUserRole.ADMIN)
  ```

  ```python Team Manager theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.utilities.project_user import ProjectUserRole

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

  # Add group to Project. Replace <project_hash> with the hash of the Project.
  project = user_client.get_project("<project_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  project.add_group(group_hashes, ProjectUserRole.TEAM_MANAGER)

  ```

  ```python Annotator + Reviewer theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.utilities.project_user import ProjectUserRole

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

  # Add group to Project. Replace <project_hash> with the hash of the Project.
  project = user_client.get_project("<project_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  project.add_group(group_hashes, ProjectUserRole.ANNOTATOR_REVIEWER)
  ```

  ```python Annotator theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.utilities.project_user import ProjectUserRole

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

  # Add group to Project. Replace <project_hash> with the hash of the Project.
  project = user_client.get_project("<project_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  project.add_group(group_hashes, ProjectUserRole.ANNOTATOR)
  ```

  ```python Reviewer theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.utilities.project_user import ProjectUserRole

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

  # Add group to Project. Replace <project_hash> with the hash of the Project.
  project = user_client.get_project("<project_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  project.add_group(group_hashes, ProjectUserRole.REVIEWER)
  ```
</CodeGroup>

### Add user group to Datasets

User groups can be added to Datasets.

In the following scripts, ensure that you:

* Replace \<private\_key\_path> with the path to your private key.
* Replace \<dataset\_hash> with the hash of the Dataset you want to add a user group to.
* Replace \<group\_name1> and \<group\_name2> with the name of the user group(s) you want to add to the Dataset. You can add one or multiple groups to a Dataset at once.

The different tabs show how to assign different roles to the user group being added to the Dataset.

<CodeGroup>
  ```python Admin theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import DatasetUserRole

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

  # Add group to Dataset. Replace <dataset_hash> with the hash of the Dataset.
  dataset = user_client.get_dataset("<dataset_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  dataset.add_group(group_hashes, DatasetUserRole.ADMIN)
  ```

  ```python User theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import DatasetUserRole

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

  # Add group to Dataset. Replace <dataset_hash> with the hash of the Dataset.
  dataset = user_client.get_dataset("<dataset_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  dataset.add_group(group_hashes, DatasetUserRole.USER)
  ```
</CodeGroup>

### Add user group to Ontologies

Use the following scripts to add user groups to Ontologies.

In the following scripts, ensure that you:

* Replace \<private\_key\_path> with the path to your private key.
* Replace \<ontology\_hash> with the hash of the Ontology you want to add a user group to.
* Replace \<group\_name1> and \<group\_name2> with the name of the user group(s) you want to add to the Ontology. You can add one, or multiple groups to an Ontology at once.

The different tabs show how to assign different roles to the user group being added to the Ontology.

<CodeGroup>
  ```python Admin theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.utilities.ontology_user import OntologyUserRole

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

  # Add group to Ontology. Replace <ontology_hash> with the hash of the Ontology.
  ontology = user_client.get_ontology("<ontology_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  ontology.add_group(group_hashes, OntologyUserRole.ADMIN)
  ```

  ```python User theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.utilities.ontology_user import OntologyUserRole

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

  # Add group to Ontology. Replace <ontology_hash> with the hash of the Ontology.
  ontology = user_client.get_ontology("<ontology_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  ontology.add_group(group_hashes, OntologyUserRole.USER)
  ```
</CodeGroup>

## Remove user groups from Projects / Datasets / Ontologies

User groups can be removed from Projects, Datasets, and Ontologies individually, or in bulk.

<Note>Admins can only be removed from Projects, Datasets, or Ontologies by Workspace admins.</Note>

In the following scripts, ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* If using the Project script, replace `<project_hash>` with the hash of the Project you want to remove user groups from.
* If using the Dataset script, replace `<dataset_hash>` with the hash of the Dataset you want to remove user groups from.
* If using the Ontology script, replace `<ontology_hash>` with the hash of the Ontology you want to remove user groups from.
* Replace `<group_name1>` and `<group_name2>` with the name of the user group(s) you want to remove from the Project. You can remove one, or multiple groups from a Project at once.

<CodeGroup>
  ```python Project theme={"dark"}
  # 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>"
      )

  # Remove group from Project. Replace <project_hash> with the hash of the Project
  project = user_client.get_project("<project_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Include as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  project.remove_group(group_hashes)
  ```

  ```python Dataset theme={"dark"}
  # 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>"
      )

  # Remove group from Dataset. Replace <dataset_hash> with the hash of the Dataset.
  dataset = user_client.get_dataset("<dataset_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Include as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  dataset.remove_group(group_hashes)
  ```

  ```python Ontology theme={"dark"}
  # 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>"
      )

  # Remove group from Ontology. Replace <ontology_hash> with the hash of the Ontology.
  ontology = user_client.get_ontology("<ontology_hash>")
  groups = user_client.list_groups()

  # Replace <group_name1> and <group_name2> with the name(s) of the group(s).
  group_names = ["<group_name1>", "<group_name2>"]  # Include as many group names as needed.
  group_hashes = [group.group_hash for group in groups if group.name in group_names]
  ontology.remove_group(group_hashes)
  ```
</CodeGroup>


# 1. Prerequisites and Installation
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/installation-sdk



## Prerequisites

Before you can utilize Encord's Python SDK, you must ensure that the following prerequisites are met:

* `pip` is installed.
* [Python 3](https://www.python.org/downloads/) is installed.

<Tip>While not strictly a requirement, we recommend that you use a virtual environment in which to install the SDK and run your projects from. See [this tutorial](https://www.freecodecamp.org/news/how-to-setup-virtual-environments-in-python/) to learn how to set up and activate virtual environments. </Tip>

***

## Installation

The Encord SDK is available through [pypi](https://pypi.org/) and is installed using the following command:

```terminal theme={"dark"}
python3 -m pip install encord
```

After successfully installing the Encord SDK, move on to the [Authentication page](/sdk-documentation/general-sdk/authentication-sdk) to learn how users get authenticated in Encord.

***

## IP Allowlisting

If your network restricts outbound traffic, add Encord's IP addresses to your allowlist to allow the Encord SDK to communicate with the Encord platform and manage your resources successfully.

<Warning>
  US Deployment refers to customers working on Encord's US-hosted instance, rather than simply being located in the United States.
</Warning>

<Tabs>
  <Tab title="Default Deployment (EMEA)">
    * `34.36.33.227/32`
  </Tab>

  <Tab title="US Deployments">
    * `34.111.173.170/32`
  </Tab>
</Tabs>

***

## Show Version Number

Always ensure you are running the latest version of the Encord SDK by using the following terminal command:

<Note>The current SDK version can be found on the [pypi page](https://pypi.org/project/encord/).</Note>

```terminal theme={"dark"}
pip show encord
```

***

### Upgrade SDK version

Upgrade your SDK version using the following command:

```terminal theme={"dark"}
pip install encord --upgrade
```


# Add Users To Your Project
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-add-users



The next step is to add different kinds of users to the Project. This includes annotators, reviewers, annotators & reviewers, project managers, and admins.

The following script adds a number of users with different user roles to your Project:

* 2 Annotators
* 2 Reviewers
* 1 Team Manager
* 1 Admin

Substitute the following values into the script below:

* `<private_key_path>` with the path to your private key.
* `<project_hash>` with the hash of your Project, output when the [Project is created](/sdk-documentation/getting-started-sdk/sdk-get-started-project).

```python theme={"dark"}
# 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>"
    )

# Substitute the hash of your Project here
project = "<project_hash>"

# Add two annotators to the Project
project.add_users(
    ["annotator1@yourdomain.com", "annotator2@yourdomain.com"],
    user_role=ProjectUserRole.ANNOTATOR,
)

# Add two reviewers to the Project
project.add_users(
    ["reviewer1@yourdomain.com", "reviewer2@yourdomain.com"],
    user_role=ProjectUserRole.REVIEWER,
)

# Add one Team Manager to the Project
project.add_users(
    ["team_manager@yourdomain.com"],
    user_role=ProjectUserRole.TEAM_MANAGER,
)

# Add one Admin to the Project
project.add_users(
    ["team_manager@yourdomain.com"],
    user_role=ProjectUserRole.ADMIN,
)
```


# Create an Ontology
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-get-started-ontology



<Note>We recommend using the [Encord platform to create Ontologies](/platform-documentation/Annotate/annotate-ontologies/annotate-create-ontologies). The platform allows you to visualize how different elements of the Ontology are related to each other.</Note>

Ontologies are used to label your data and define how concepts are related to each other.

The following script creates an Ontology called "My test Ontology" containing an object called `Cute Cat`, a radio button attribute for `colour`, and a checklist attribute for `features`. Examples for bounding boxes, rotatable bounding boxes, polygons, and bitmasks are provided.

The script outputs the hash of the Ontology. The hash is used for the creation of a Project.

Ensure you replace:

* `<file-path-to-ssh-private-key>` with the pull path to your private key.
* `My test Ontology` with the name of your Ontology.
* `Cute Cat` with the name of your Ontology class.
* As well as any other options relevant to your Ontology.

<CodeGroup>
  ```python Bounding Box theme={"dark"}
  from encord import EncordUserClient
  from encord.objects import Shape, Object, Option, OntologyStructure
  from encord.ontology import Ontology
  from encord.objects.attributes import RadioAttribute, ChecklistAttribute



  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path='<file-path-to-ssh-private-key>'
      )

  ontology_structure = OntologyStructure()

  # Adding bounding box annotation
  ontology_structure.add_object("Cute Cat", shape=Shape.BOUNDING_BOX)


  # Adding a Classification of type radio button
  classification = ontology_structure.add_classification()
  cat_colour = classification.add_attribute(RadioAttribute, "colour", required=True)
  cat_colour.add_option("white")
  cat_colour.add_option("black")

  # Adding a Classification of type check box
  classification = ontology_structure.add_classification()
  cat_features = classification.add_attribute(ChecklistAttribute, "features")
  cat_features.add_option("soft")
  cat_features.add_option("fluffy")
  cat_features.add_option("friendly")

  cat_ontology = user_client.create_ontology(title="My test Ontology", structure=ontology_structure)

  # Prints the ontology hash
  print (cat_ontology.ontology_hash)

  ```

  ```python Rotatable Bounding Box theme={"dark"}
  from encord import EncordUserClient
  from encord.objects import Shape, Object, Option, OntologyStructure
  from encord.ontology import Ontology
  from encord.objects.attributes import RadioAttribute, ChecklistAttribute


  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path='<file-path-to-ssh-private-key>'
      )

  ontology_structure = OntologyStructure()

  # Adding bounding box annotation
  ontology_structure.add_object("Cute Cat", shape=Shape.BOUNDING_BOX)


  # Adding a Classification of type radio button
  classification = ontology_structure.add_classification()
  cat_colour = classification.add_attribute(RadioAttribute, "colour", required=True)
  cat_colour.add_option("white")
  cat_colour.add_option("black")

  # Adding a Classification of type check box
  classification = ontology_structure.add_classification()
  cat_features = classification.add_attribute(ChecklistAttribute, "features")
  cat_features.add_option("soft")
  cat_features.add_option("fluffy")
  cat_features.add_option("friendly")

  cat_ontology = user_client.create_ontology(title="My test Ontology", structure=ontology_structure)

  # Prints the ontology hash
  print (cat_ontology.ontology_hash)

  ```

  ```python Polygon theme={"dark"}
  from encord import EncordUserClient
  from encord.objects import Shape, Object, Option, OntologyStructure
  from encord.ontology import Ontology
  from encord.objects.attributes import RadioAttribute, ChecklistAttribute


  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path='<file-path-to-ssh-private-key>'
      )

  ontology_structure = OntologyStructure()

  # Adding bounding box annotation
  ontology_structure.add_object("Cute Cat", shape=Shape.POLYGON)


  # Adding a Classification of type radio button
  classification = ontology_structure.add_classification()
  cat_colour = classification.add_attribute(RadioAttribute, "colour", required=True)
  cat_colour.add_option("white")
  cat_colour.add_option("black")

  # Adding a Classification of type check box
  classification = ontology_structure.add_classification()
  cat_features = classification.add_attribute(ChecklistAttribute, "features")
  cat_features.add_option("soft")
  cat_features.add_option("fluffy")
  cat_features.add_option("friendly")

  cat_ontology = user_client.create_ontology(title="My test Ontology", structure=ontology_structure)

  # Prints the ontology hash
  print (cat_ontology.ontology_hash)

  ```

  ```python Bitmask theme={"dark"}
  from encord import EncordUserClient
  from encord.objects import Shape, Object, Option, OntologyStructure
  from encord.ontology import Ontology
  from encord.objects.attributes import RadioAttribute, ChecklistAttribute

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path='<file-path-to-ssh-private-key>'
      )

  ontology_structure = OntologyStructure()

  # Adding bounding box annotation
  ontology_structure.add_object("Cute Cat", shape=Shape.BITMASK)


  # Adding a Classification of type radio button
  classification = ontology_structure.add_classification()
  cat_colour = classification.add_attribute(RadioAttribute, "colour", required=True)
  cat_colour.add_option("white")
  cat_colour.add_option("black")

  # Adding a Classification of type check box
  classification = ontology_structure.add_classification()
  cat_features = classification.add_attribute(ChecklistAttribute, "features")
  cat_features.add_option("soft")
  cat_features.add_option("fluffy")
  cat_features.add_option("friendly")

  cat_ontology = user_client.create_ontology(title="My test Ontology", structure=ontology_structure)

  # Prints the ontology hash
  print (cat_ontology.ontology_hash)

  ```
</CodeGroup>


# Create a Project
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-get-started-project



Once you have your data, your Ontology, and a Workflow template, it is time to create a Project. Labels are created and reviewed within Projects. Projects tie together Datasets, Ontologies, and labels.

Substitute the following values into the script below:

* \<private\_key\_path> with the path to your private key.
* \<project\_title> with the title you want to give the Project.
* \<dataset\_hash> with the hash of the Dataset(s) you want to attach to the Project.
* \<ontology\_hash> with the hash of the Ontology you created for this Project (output in [Step 1](/sdk-documentation/getting-started-sdk/sdk-get-started-ontology)).
* \<template\_hash> with the hash of the Workflow template. To use the default Workflow template the `workflow_template_hash` argument must be omitted.

<Warning>
  If a \<template\_hash> is omitted a Workflow Project with the default **Standard workflow** is created.
</Warning>

<Tip>
  To use an existing template when creating a Project, users must have Admin privileges on the template. We recommend creating a copy of the Workflow template before Project creation, to ensure you have Admin privileges.
</Tip>

<CodeGroup>
  ```python Sample Code theme={"dark"}
  # 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)
  ```

  ```Example output theme={"dark"}
  a8b8d026-1c99-4cfc-910d-7f66be957f3d
  ```
</CodeGroup>


# Create a Workflow Template
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-get-started-workflow-template



<Info>Workflow templates must be created using the Encord platform. [See our documentation](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#creating-templates) to learn more.</Info>

Workflows establish how labeling tasks move through your Project and how they are assigned.

Go to **Annotate > Projects** and select *Workflow templates* tab from the *Projects* page, and click the **+ Create template**. Previously created templates are visible here, and can be [edited](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#edit-templates) when selected.

<iframe title="YouTube video player" />

Name and then configure your workflow template, then click the **Save changes** button when you are done. To learn how to create and configure workflows, see our documentation [here](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#creating-workflows).

The **Save changes** button is grayed out until:

* The nodes in your template have been connected.
* The workflow contains a ***Complete*** stage.

Take note of the Workflow template hash. The template hash is used to reference the template in Step 3.


# Encord SDK Introduction
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-intro



Encord is an end-to-end platform for AI-assisted annotation, quality control, and data management for computer vision and multimodal AI. It empowers teams to efficiently build high-quality datasets for training and evaluating machine learning models.

The Encord SDK provides a powerful Python interface for interacting with the Encord platform programmatically. It allows developers and data scientists to create automated pipelines and integrate Encord functionalities directly into their existing MLOps workflows.

<Tip>
  The SDK is especially recommended for customers working with large quantities of data.
</Tip>

<CardGroup>
  <Card title="Install the SDK" icon="play" href="/sdk-documentation/getting-started-sdk/installation-sdk">
    Learn how to install the Encord SDK and keep it up to date.
  </Card>

  <Card title="Authentication" icon="plug" href="/sdk-documentation/general-sdk/authentication-sdk">
    Learn how to Authenticate with Encord. Authentication differs for US customers.
  </Card>

  <Card title="Add Data" icon="plus" href="/sdk-documentation/getting-started-sdk/sdk-register-data-aws">
    Lean how to add your data to Encord.
  </Card>

  <Card title="Export Labels" icon="file-export" href="/sdk-documentation/sdk-labels/sdk-export">
    Lean how to export your labels from Encord.
  </Card>
</CardGroup>


# Import/Register Data (SDK)
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-register-data



<CardGroup>
  <Card title="Register AWS Data" icon="aws" href="/sdk-documentation/getting-started-sdk/sdk-register-data-aws">
    Learn how to register your data from AWS.
  </Card>

  <Card title="Register GCP Data" icon="google" href="/sdk-documentation/getting-started-sdk/sdk-register-data-gcp">
    Learn how to register your data from GCP.
  </Card>

  <Card title="Register Azure Data" icon="microsoft" href="/sdk-documentation/getting-started-sdk/sdk-register-data-azure">
    Learn how to register your data from Azure.
  </Card>

  <Card title="Register OTC Data" icon="https://storage.googleapis.com/docs-media.encord.com/static/img/open-telekom.png" href="/sdk-documentation/getting-started-sdk/sdk-register-data-otc">
    Learn how to import your local data.
  </Card>
</CardGroup>


# Register AWS Data (SDK)
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-register-data-aws



Using cloud storage data in Encord is a multi-step process:

1. Set up your cloud storage so Encord can access your data

2. Create a cloud storage integration on Encord to link to your cloud storage

3. Create a Dataset

4. Create a JSON or CSV file to register your data

5. Perform the registration using the JSON or CSV file

<Tip>See our [AWS integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration) for a detailed guide to setting up an integration.</Tip>

***

## Step 1: Set up AWS

Before you can do anything with the Encord platform and cloud storage, you need to configure your cloud storage to work with Encord. Once the integration between Encord and your cloud storage is complete, you can then use your data in Encord.

In order to integrate with AWS S3, you need to:

1. Create a permission policy for your resources that allows appropriate access to Encord.
2. Create a role for Encord and attach the policy so that Encord can access those resources.
3. Activate Cross-origin resource sharing which allows Encord to access those resources from a web browser.
4. Test the integration to make sure it works.

<Tip>See our [AWS integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration) for a detailed explanation of setting up AWS to work with Encord.</Tip>

You have the following options to integrate AWS and Encord:

<div lang="en">
  <head>
    <meta />

    <meta name="viewport" />

    <title>Clickable Div</title>
  </head>

  <div>
    <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration">
      Use AWS UI
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-aws-integration#terraforming-your-aws-s3-integration">
      Use Terraform
    </a>
  </div>
</div>

## Step 2: Create AWS-Encord Integration

<Note>Create an S3 bucket to store your files if you haven't already. Your S3 bucket permissions should be set to be blocking all public access.</Note>

In the *Integrations* section of the Encord platform, click **+New integration** to create a new integration.

<div>
  <img />
</div>

Select *AWS S3* at the top of the chooser.

<div>
  <img />
</div>

<Note>It is essential you do not close this tab or window until you have finished the whole integration process. If you use the AWS UI for integration, we advise opening the AWS console in a separate tab.</Note>

<Tip>See our [AWS integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-aws-integration) for a detailed explanation of how to set up the AWS integration.</Tip>

## Step 3: Create JSON or CSV for Registration

All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

<Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data)</Note>

<Info>Encord supports file names up to 300 characters in length for any file or video for upload.</Info>

<Info>
  Encord enforces the following upload limits for each JSON file used for file registration:

  * Up to 1 million URLs
  * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  * URLs can be up to 16 KB in size

  Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
</Info>

<Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

### Create JSON file for Registration

For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

<Note>If `skip_duplicate_urls` is set to `true`, all object URLs that exactly match existing images/videos in the dataset are skipped.</Note>

***

<AccordionGroup>
  <Accordion title="Videos">
    #### [Videos](#videos)

    **Video Metadata**

    When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

    <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "cloud-path-to-your-video-1"
          },
          {
            "objectUrl": "cloud-path-to-your-video-2",
              "videoMetadata": {
                "fps": frames-per-second,
                "duration": duration-in-seconds,
                "width": frame-width,
                "height": frame-height,
                "file_size": file-size-in-bytes,
                "mime_type": "MIME-file-type-extension"
              }
            }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/BerghouseLeopardJog.mp4"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blue_bus_video.mp4"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/bluemlisalphutte_flyover.mp4"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake_normalized.mp4"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/boat_lake.MP4"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/snow_sled.MOV"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cyclists.MP4"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Video Metadata theme={"dark"}
      {
          "videos": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/video_file.mp4",
              "videoMetadata": {
                  "fps": 23.98,
                  "duration": 29.09,
                  "width": 1280,
                  "height": 720,
                  "file_size": 5468354,
                  "mime_type": "video/mp4"
              }
            }
          ],
        "skip_duplicate_urls": true
        }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Audio files">
    #### [Audio Files](#audio-files)

    The following is an example JSON file for uploading two audio files to Encord.

    <Tip>
      Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
    </Tip>

    * **Template:** Imports audio files with an Encord title.
    * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "audio": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-custom-audio-file-title.mp3"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Audio Metadata theme={"dark"}
      {
          "audio": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file.mp3",
              "audioMetadata": {
                  "duration": 23.98,
                  "file_size": 2900000,
                  "mime_type": "audio/mp3",
                  "sample_rate": 44100,
                  "bit_depth": 24,
                  "codec": "mp3",
                  "num_channels": 2
              }
            }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="PDFs">
    #### [PDFs](#pdfs)

    The following are example JSON files for uploading PDFs to Encord.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-document-02.pdf"
          },
          {
            "objectUrl": "<object url_3>",
            "title": "my-document-03.pdf",
            "pdfMetadata": {
              "fileSize": 300,
              "numPages": 5
              }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "pdfs": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-01.pdf",

            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-02.pdf",
              "title": "my-document-02.pdf"
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-03.pdf",
              "title": "my-document-03.pdf",
              "pdfMetadata": {
                "fileSize": 300,
                "numPages": 5
                }
            }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Text Files">
    #### [Text Files](#text-files)

    The following are example JSON files for uploading text files to Encord.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-file.html"
          },
          {
            "objectUrl": "<object url_3>",
            "title": "my-plain-text-file.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "<object url_4>",
            "title": "my-csv-file.csv",
            "textMetadata": {
              "fileSize": 250,
              "mime_type": "text/csv"
            }
          },
          {
            "objectUrl": "<object url_5>",
            "title": "my-xml-file.xml",
            "textMetadata": {
              "fileSize": 300,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "<object url_6>",
            "title": "my-html-file.html",
            "textMetadata": {
              "fileSize": 400,
              "mime_type": "text/html"
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "text": [
            {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-file-01.html"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-01.txt",
            "title": "my-plain-text-file-01.txt"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-plain-text-file-02.txt",
            "title": "my-plain-text-file-02.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-csv-file-01.csv",
            "title": "my-csv-file-01.csv",
            "textMetadata": {
              "fileSize": 250,
              "mime_type": "text/csv"
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-xml-file-01.xml",
            "title": "my-xml-file-01.xml",
            "textMetadata": {
              "fileSize": 300,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/text/my-html-file-01.html",
            "title": "my-html-file-01.html",
            "textMetadata": {
              "fileSize": 400,
              "mime_type": "text/html"
            }
          }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    #### [Single Images](#single-images)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    The JSON structure for single images parallels that of videos.

    **Template:** Provides the proper JSON format to import images into Encord.

    **Examples:**

    * **Data** Imports the images only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/images/file-name-01.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-02.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-03.file-extension",
            "title": "image-title.file-extension"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data    theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.jpg"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0003.jpg"
          },
          {
            "objectUrl": "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"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/large_images/pexels-ivo-rainha-00057.png"
          }
        ]
      }
      ```

      ```json Image Metadata theme={"dark"}

      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/my_image.jpg",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### [Image groups](#image-groups)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image groups are collections of images that are processed as one annotation task.
    * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
    * Image groups do NOT require 'write' permissions to your cloud storage.
    * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the image groups only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "image_groups": [
          {
            "title": "<title 1>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
          },
          {
            "title": "<title 2>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Image group 01",
            "createVideo": false,
            "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg",
            "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.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 group 02",
            "createVideo": false,
            "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0001.jpg",
            "objectUrl_1": "<https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0002.jpg",
            "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0003.jpg"
          }
        ],
        "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### [Image sequences](#image-sequences)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image sequences are collections of images that are processed as one annotation task and represented as a video.
    * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
    * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
    * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
    * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

    <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the images groups only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "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>"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "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
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    #### [DICOM](#dicom)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Each `dicom_series` element can contain one or more DICOM series.
    * Each series requires a title and at least one object URL, as shown in the example below.
    * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

    <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

    The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

    * The first series contains only a single object URL, as it is composed of a single file.
    * The second series contains 3 object URLs, as it is composed of three separate files.
    * The third series contains 2 object URLs, as it is composed of two separate files.

    <Info>
      For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
    </Info>

    ```json Template theme={"dark"}
    {
      "dicom_series": [
        {
          "title": "Series-1",
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series1-file.dcm"
        },
        {
          "title": "Series-2",
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file1.dcm",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file2.dcm",
          "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file3.dcm",
        },
          {
          "title": "Series-3",
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file1.dcm",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file2.dcm",
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="NIfTI">
    #### [NIfTI](#nifti)

    The following is an example JSON file for uploading two NIfTI files to Encord.

    ```json Template theme={"dark"}
    {
        "nifti": [
          {
            "title": "<file-1>",
            "objectUrl": "https://my-bucket/.../nifti-file1.nii"
          },
          {
            "title": "<file-2>",
            "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
          }
        ],
        "skip_duplicate_urls": true
      }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

    ```json Multiple file types theme={"dark"}

    {
      "images": [
        {
          "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/Image1.png"
        }
      ],
      "videos": [
        {
          "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Cooking.mp4"
        },
        {
          "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Oranges.mp4"
        }
      ],
      "image_groups": [
        {
          "title": "apple-samsung-light",
          "createVideo": true,
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(32).jpg",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
          "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
          "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
        },
        {
          "title": "apple-samsung-dark",
          "createVideo": true,
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(32).jpg",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(33).jpg",
          "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(34).jpg",
          "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(35).jpg"
        }
      ],
      "image_groups": [
        {
          "title": "apple-ios-light",
          "createVideo": false,
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(32).jpg",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(33).jpg"
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

***

#### Use a Multi-Region Access Point

When using a Multi-Region Access Point for your AWS S3 buckets the JSON file has to be slightly different from the examples provided. Instead of an object's URL, objects are specified using the ARN of the Multi-Region Access Point followed by the object name. The example below shows how video files from a Multi-Region Access Point would be specified.

```json theme={"dark"}
{
  "videos": [
    {
      "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
    },
    {
      "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
      "title": "my-custom-video-title.mp4"
    }
  ],
  "skip_duplicate_urls": true
}
```

```json MRAP Example theme={"dark"}
{
  "videos": [
    {
      "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_1.mp4"
    },
    {
      "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_2.mp4",
      "title": "many-cute-cats.mp4"
    }
  ],
  "skip_duplicate_urls": true
}
```

***

### Create CSV File for Registration

In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file.

Details for each data format are given in the sections below.

<Info>Encord supports up to 10,000 entries for upload in the CSV file.</Info>

<Warning>
  * Object URLs can't contain whitespace.
  * For backwards compatibility reasons, a single column CSV is supported. A file with the single `ObjectUrl` column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: "Expected a video, got a file of type XXX".
</Warning>

<AccordionGroup>
  <Accordion title="Videos">
    #### Videos

    A CSV file containing videos should contain two columns with the following mandatory column headings:\
    'ObjectURL' and 'Video title'. All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the video resource.

    * The 'Video title' column containing the `video_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Video title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.mp4 | Video 1     |
    | path/to/storage-location/frame2.mp4 | Video 2     |
    | path/to/storage-location/frame3.mp4 |             |
    | path/to/storage-location/frame4.mp4 | Video 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    A CSV file containing single images should contain two columns with the following mandatory headings:\
    'ObjectURL' and 'Image title'.  All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the image resource.

    * The 'Image title' column containing the `image_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Image title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.jpg | Image 1     |
    | path/to/storage-location/frame2.jpg | Image 2     |
    | path/to/storage-location/frame3.jpg |             |
    | path/to/storage-location/frame4.jpg | Image 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### Image groups

    A CSV file containing image groups should contain three columns with the following mandatory headings:\
    'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image group a file will be assigned to.

    In the example below the first two URLs are grouped together into 'Group 1', while the following two files are grouped together into 'Group 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Group 1           | false        |
    | path/to/storage-location/frame2.jpg | Group 1           | false        |
    | path/to/storage-location/frame3.jpg | Group 2           | false        |
    | path/to/storage-location/frame4.jpg | Group 2           | false        |

    <Note>Image groups do not require 'write' permissions.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### Image sequences

    A CSV file containing image sequences should contain three columns with the following mandatory headings: 'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.

    * The 'Create video' column. This can be left blank, as the default value is 'true'.

    In the example below the first two URLs are grouped together into 'Sequence 1', while the second two files are grouped together into 'Sequence 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |

    <Tip>Image groups and image sequences are only distinguished by the presence of the 'Create video' column.</Tip>

    <Note>Image sequences require 'write' permissions against your storage bucket to save the compressed video.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    A CSV file containing DICOM files should contain two columns with the following mandatory headings: 'ObjectURL' and 'Dicom title'. Both headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Series title' column containing the `dicom_title`. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.

    In the example below the first two files are grouped into 'dicom series 1', the next two files are grouped into 'dicom series 2', while the final file will remain separated as 'dicom series 3'.

    | ObjectUrl                           | Series title   |
    | ----------------------------------- | -------------- |
    | path/to/storage-location/frame1.dcm | dicom series 1 |
    | path/to/storage-location/frame2.dcm | dicom series 1 |
    | path/to/storage-location/frame3.dcm | dicom series 2 |
    | path/to/storage-location/frame4.dcm | dicom series 2 |
    | path/to/storage-location/frame5.dcm | dicom series 3 |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    #### Multiple file types

    You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.

    <Warning>Since the 'Create video' column defaults to `true` all files that **are not** image sequences must contain the value `false`</Warning>

    The example below shows a CSV file for the following:

    * Two image sequences composed of 2 files each.
    * One image group composed of 2 files.
    * One single image.
    * One video.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame5.jpg | Group 1           | false        |
    | path/to/storage-location/frame6.jpg | Group 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | path/to/storage-location/frame1.jpg | Image 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | full/storage/path/video.mp4         | Video 1           | false        |
  </Accordion>
</AccordionGroup>

***

## Step 4: Register Data with Encord

To use your data in Encord, it must be uploaded to the Encord **Files & Folders** storage. Once uploaded, your data can be reused across multiple Projects and contain no labels or annotations themselves. **Files & Folders** stores your data, while *Projects* store your labels. The following script creates a folder in **Files & Folders** and uses your AWS integration to register data in that folder.

The following script creates a new folder in **Files & Folders** and initiates uploads from AWS. It works for all file types.

<Tip>If `Upload is still in progress, try again later!` is returned, use the
[script to check the upload status](/sdk-documentation/getting-started-sdk/sdk-register-data-aws#step-5-check-data-upload) to see whether the upload has finished.</Tip>

Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<integration_title>` with the title of the integration you want to use.
* Replace `<folder_name>` with the folder name. The scripts assume that the specified folder name is unique.
* Replace `path/to/json/file.json` with the path to a [JSON file specifying which cloud storage files should be uploaded](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).
* Replace `A folder to store my files` with a meaningful description for your folder.
* Replace `"my": "folder_metadata"` with any metadata you want to add to the folder.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.
* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.
* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

<CodeGroup>
  ```python Create folder and register cloud data theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus  # Ensure correct import path

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

  # Specify the integration you want to use
  integrations = user_client.get_cloud_integrations()
  integration_idx = [i.title for i in integrations].index("<integration_title>")
  integration = integrations[integration_idx].id

  # Create a storage 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
  )

  # Initiate cloud data registration
  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
  )

  # Check upload status
  res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
  print(f"Execution result: {res}")

  if res.status == LongPollingStatus.PENDING:
      print("Upload is still in progress, try again later!")
  elif res.status == LongPollingStatus.DONE:
      print("Upload completed")
      if res.unit_errors:
          print("The following URLs failed to upload:")
          for e in res.unit_errors:
              print(e.object_urls)
  else:
      print(f"Upload failed: {res.errors}")

  ```

  ```Example output theme={"dark"}
  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.
  ```
</CodeGroup>

***

### Step 5: Check Registration Status

If Step 5 returns `"Upload is still in progress, try again later!"`, run the following code to query the Encord server again. Ensure that you replace `<upload_job_id>` with the output by the previous code. In the example above upload\_job\_id=`c4026edb-4fw2-40a0-8f05-a1af7f465727`.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.

* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.

* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

```python theme={"dark"}
# Import dependencies
from uuid import UUID
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus
from encord.storage import StorageFolder 

upload_job_id = "<upload_job_id>"
folder_id = "<folder_uuid>" 

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

# Get the storage folder by ID
storage_folder = user_client.get_storage_folder(UUID(folder_id))

# Check upload status
res = storage_folder.add_private_data_to_folder_get_result(
    upload_job_id=UUID(upload_job_id),
    timeout_seconds=30,
)
print(f"Execution result: {res}")

if res.status == LongPollingStatus.PENDING:
    print("Upload is still in progress, try again later!")
elif res.status == LongPollingStatus.DONE:
    print("Upload completed")
    if res.unit_errors:
        print("The following URLs failed to upload:")
        for e in res.unit_errors:
            print(e.object_urls)
else:
    print(f"Upload failed: {res.errors}")
```

<Tip>Omitting the `timeout_seconds` argument from the
[add\_private\_data\_to\_dataset\_get\_result()](/sdk-documentation/sdk-references/dataset#add-private-data-to-dataset-get-result) method performs status checks until the status upload has finished.</Tip>

***

## Step 6: Create a Dataset

<Note>Creating a Dataset and adding files to a Dataset are two distinct steps. [Click here](/sdk-documentation/index-sdk/sdk-add-files-to-datasets) to learn how to add data to an existing Dataset.</Note>

<Info>Datasets cannot be deleted using the SDK or the API. Use the Encord platform to delete Datasets. </Info>

The following example creates a Dataset called “Houses” that expects data hosted on AWS S3.

* Substitute `<private_key_path>` with the file path for your private key.
* Replace "Houses" with the name you want your Dataset to have.

<CodeGroup>
  ```python Example code theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import StorageLocation

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

  # Create a new dataset
  dataset_response = user_client.create_dataset(
      dataset_title="Houses",
      dataset_type=StorageLocation.AWS,
      create_backing_folder=False,
  )

  # Prints a CreateDatasetResponse object. Verify the Dataset creation
  print(dataset_response)

  # Print the storage location
  print(f"Using storage location: AWS")
  ```

  ```python Example output theme={"dark"}
  {
  {'title': 'Houses', 'type': 1, 'dataset_hash': 'd2bbbaed-cf33-4583-81b5-f30691abde1d', 'user_hash': 'iaDJxNNrMuQMtFPcP9oszw2OCHm2', 'backing_folder_uuid': UUID('5f8364e8-8ccd-4f9f-9066-91e055da920d')}
  }
  ```
</CodeGroup>

## Step 7: Add Your Data to a Dataset

Now that you uploaded your data and created a Dataset, it is time to add your files to the Dataset. The following scripts add all files in a specified folder to a Dataset.

* Replace `<private_key_path>` with the path to your private key.
* Replace `<folder_name>` with the name you want to give your Storage folder.
* Replace `<dataset_hash>` with the hash of the Dataset you want to add the data units to.

<Note>Files added to the folder at a later time **will not** be automatically added to the Dataset.</Note>

```python All files theme={"dark"}
from encord import EncordUserClient

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1))

dataset = user_client.get_dataset("<dataset_hash>")

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List all data units
    items = list(storage_folder.list_items())

    # Collect all item UUIDs
    item_uuids = [item.uuid for item in items]

    # Output the retrieved data units
    for item in items:
        print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")

    # Link all items at once if there are any
    if item_uuids:
        dataset.link_items(item_uuids)
else:
    print("Folder not found.")
```

## Step 8: Verify Your Files Are in the Dataset

After adding your files to the Dataset, verify that all the files you expect to be there made it into the Dataset.

The following script prints the URLs of all the files in a Dataset. Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<dataset_hash>` with the hash of your Dataset.

```python Sample Code theme={"dark"}
#Import dependencies
from encord import EncordUserClient, Project,Dataset
from encord.objects.project import ProjectDataset
from encord.orm.dataset import DatasetAccessSettings

#Initiate client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

#Files the file links to all files in the Dataset
dataset_level_file_links = []
dataset: Dataset = user_client.get_dataset("<dataset_hash>")
for data in dataset.list_data_rows():
    dataset_level_file_links.append(data.file_link)
print(dataset_level_file_links)
```

***

## Step 9: Prepare Your Data for Label/Annotation Import

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/sdk-documentation/getting-started-sdk/sdk-get-started-ontology">
      Prepare Data for Labels
    </a>
  </div>
</>

***

## Step 10: Import Labels/Annotations

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual">
      Import Labels/Annotations
    </a>
  </div>
</>


# Register Azure Data (SDK)
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-register-data-azure



Using cloud storage data in Encord is a multi-step process:

1. Set up your cloud storage so Encord can access your data

2. Create a cloud storage integration on Encord to link to your cloud storage

3. Create a Dataset

4. Create a JSON or CSV file to register your data

5. Perform the registration using the JSON or CSV file

<Tip>See our [Azure integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration) for a detailed guide to setting up an integration.</Tip>

## Step 1: Create Encord Integration

Before you can do anything with the Encord platform and cloud storage, you need to configure your cloud storage to work with Encord. Once the integration between Encord and your cloud storage is complete, you can then use your data in Encord.

In order to integrate Azure with Encord you need to:

1. Create the integration with the Encord platform ([https://app.encord.com/integrations](https://app.encord.com/integrations) or [https://app.us.encord.com/integrations](https://app.us.encord.com/integrations)).

2. Authenticate your storage account for integration on the [Azure platform](https://portal.azure.com/#home).

3. Set up Cross-Origin Resource Sharing (CORS) on Azure.

In Encord, navigate to the *Integrations* section and click the **Add integration** button.

<div>
  <img />
</div>

Navigate to the *Azure* tab and type the name of the storage account you registered in step 1 of the integration into the first dropdown in the Azure integrations window, as shown below.

<div>
  <img />
</div>

Select your preferred method of authentication in the second dropdown of the Azure integrations window.

* Shared access signature.
* (Legacy) Azure service principal.

<div>
  <img />
</div>

Optionally check the box to enable **Strict client-only access, server-side media features will not be available** if you would like Encord to sign URLs, but refrain from downloading any media files onto Encord servers. Read more about this feature [here](/platform-documentation/General/annotate-data-integrations#strict-client-only-access).

<div>
  <img />
</div>

## Step 2: Setup Azure Integration

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration#2-authenticating-azure">
      Step 1: Authenticate Azure
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-azure-blob-integration#3-creating-a-cors-configuration-in-azure">
      Step 2: Configure CORS
    </a>
  </div>
</>

## Step 3: Create JSON or CSV for Registration

All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

<Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data)</Note>

<Info>Encord supports file names up to 300 characters in length for any file or video for upload.</Info>

<Info>
  Encord enforces the following upload limits for each JSON file used for file registration:

  * Up to 1 million URLs
  * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  * URLs can be up to 16 KB in size

  Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
</Info>

<Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

### Create JSON file for Registration

For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

<Note>If `skip_duplicate_urls` is set to `true`, all object URLs that exactly match existing images/videos in the dataset are skipped.</Note>

***

<AccordionGroup>
  <Accordion title="Videos">
    #### [Videos](#videos)

    **Video Metadata**

    When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

    <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "cloud-path-to-your-video-1"
          },
          {
            "objectUrl": "cloud-path-to-your-video-2",
              "videoMetadata": {
                "fps": frames-per-second,
                "duration": duration-in-seconds,
                "width": frame-width,
                "height": frame-height,
                "file_size": file-size-in-bytes,
                "mime_type": "MIME-file-type-extension"
              }
            }
          {
            "objectUrl": "cloud-path-to-your-video-3",
            "title": "title-for-your-video-3"

          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/BerghouseLeopardJog.mp4"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/blue_bus_video.mp4"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/bluemlisalphutte_flyover.mp4"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake_normalized.mp4"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/boat_lake.MP4"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/snow_sled.MOV"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/cyclists.MP4"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Video Metadata theme={"dark"}
      {
          "videos": [
            {
              "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/video_file.mp4",
              "videoMetadata": {
                  "fps": 23.98,
                  "duration": 29.09,
                  "width": 1280,
                  "height": 720,
                  "file_size": 5468354,
                  "mime_type": "video/mp4"
              }
            }
          ],
          "skip_duplicate_urls": true
        }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Audio files">
    #### [Audio Files](#audio-files)

    The following is an example JSON file for uploading two audio files to Encord.

    <Tip>
      Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
    </Tip>

    * **Template:** Imports audio files with an Encord title.
    * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "audio": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-custom-audio-file-title.mp3"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Audio Metadata theme={"dark"}
      {
          "audio": [
            {
              "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/audio_file.mp3",
              "audioMetadata": {
                  "duration": 23.98,
                  "file_size": 2900000,
                  "mime_type": "audio/mp3",
                  "sample_rate": 44100,
                  "bit_depth": 24,
                  "codec": "mp3",
                  "num_channels": 2
              }
            }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="PDFs">
    #### [PDFs](#pdfs)

    The following are example JSON files for uploading PDFs to Encord.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-document-02.pdf"
          },
          {
            "objectUrl": "<object url_3>",
            "title": "my-document-03.pdf",
            "pdfMetadata": {
              "fileSize": 300,
              "numPages": 5
              }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "pdfs": [
            {
              "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-01.pdf",

            },
            {
              "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-02.pdf",
              "title": "my-document-02.pdf"
            },
            {
              "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-document-03.pdf",
              "title": "my-document-03.pdf",
              "pdfMetadata": {
                "fileSize": 300,
                "numPages": 5
                }
            }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Text Files">
    #### [Text Files](#text-files)

    The following are example JSON files for uploading text files to Encord.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-file.html"
          },
          {
            "objectUrl": "<object url_3>",
            "title": "my-plain-text-file.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "<object url_4>",
            "title": "my-csv-file.csv",
            "textMetadata": {
              "fileSize": 250,
              "mime_type": "text/csv"
            }
          },
          {
            "objectUrl": "<object url_5>",
            "title": "my-xml-file.xml",
            "textMetadata": {
              "fileSize": 300,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "<object url_6>",
            "title": "my-html-file.html",
            "textMetadata": {
              "fileSize": 400,
              "mime_type": "text/html"
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "text": [
            {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-file-01.html"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-01.txt",
            "title": "my-plain-text-file-01.txt"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-plain-text-file-02.txt",
            "title": "my-plain-text-file-02.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-csv-file-01.csv",
            "title": "my-csv-file-01.csv",
            "textMetadata": {
              "fileSize": 250,
              "mime_type": "text/csv"
            }
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-xml-file-01.xml",
            "title": "my-xml-file-01.xml",
            "textMetadata": {
              "fileSize": 300,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my-html-file-01.html",
            "title": "my-html-file-01.html",
            "textMetadata": {
              "fileSize": 400,
              "mime_type": "text/html"
            }
          }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    #### [Single Images](#single-images)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    The JSON structure for single images parallels that of videos.

    **Template:** Provides the proper JSON format to import images into Encord.

    **Examples:**

    * **Data** Imports the images only.

    * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/images/file-name-01.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-02.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-03.file-extension",
            "title": "image-title.file-extension"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/0003.jpg"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
          },
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/large_images/pexels-ivo-rainha-00057.png"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Image Metadata theme={"dark"}

      {
        "images": [
          {
            "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/my_image.jpg",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### [Image groups](#image-groups)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image groups are collections of images that are processed as one annotation task.
    * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
    * Image groups do NOT require 'write' permissions to your cloud storage.
    * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the image groups only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "image_groups": [
          {
            "title": "<title 1>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
          },
          {
            "title": "<title 2>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Image group 01",
            "createVideo": false,
            "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/0001.jpg",
            "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/0002.jpg",
            "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
          },
          {
            "title": "Image group 02",
            "createVideo": false,
            "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0001.jpg",
            "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/images/thing-0002.jpg",
            "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-0003.jpg"
          }
        ],
        "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### [Image sequences](#image-sequences)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image sequences are collections of images that are processed as one annotation task and represented as a video.
    * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
    * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
    * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
    * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

    <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the images groups only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "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>"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Image sequence 001",
            "createVideo": true,
            "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/01.jpg",
            "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/02.jpg",
            "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/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://myaccount.blob.core.windows.net/encordcontainer/thing-01.jpg",
            "objectUrl_1": "<https://myaccount.blob.core.windows.net/encordcontainer/thing-02.jpg",
            "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/thing-03.jpg"
          }
        ],
        "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    #### [DICOM](#dicom)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Each `dicom_series` element can contain one or more DICOM series.
    * Each series requires a title and at least one object URL, as shown in the example below.
    * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

    <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

    The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

    * The first series contains only a single object URL, as it is composed of a single file.
    * The second series contains 3 object URLs, as it is composed of three separate files.
    * The third series contains 2 object URLs, as it is composed of two separate files.

    <Info>
      For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
    </Info>

    ```json Template theme={"dark"}
    {
      "dicom_series": [
        {
          "title": "Series-1",
          "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series1-file.dcm"
        },
        {
          "title": "Series-2",
          "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file1.dcm",
          "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file2.dcm",
          "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file3.dcm",
        },
          {
          "title": "Series-3",
          "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file1.dcm",
          "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file2.dcm",
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="NIfTI">
    #### [NIfTI](#nifti)

    The following is an example JSON file for uploading two NIfTI files to Encord.

    ```json Template theme={"dark"}
    {
        "nifti": [
          {
            "title": "<file-1>",
            "objectUrl": "https://my-bucket/.../nifti-file1.nii"
          },
          {
            "title": "<file-2>",
            "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
          }
        ],
        "skip_duplicate_urls": true
      }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

    ```json theme={"dark"}

    {
      "images": [
        {
          "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Image1.png"
        }
      ],
      "videos": [
        {
          "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Cooking.mp4"
        },
        {
          "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Oranges.mp4"
        }
      ],
      "image_groups": [
        {
          "title": "apple-samsung-light",
          "createVideo": true,
          "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(32).jpg",
          "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(33).jpg",
          "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(34).jpg",
          "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(35).jpg"
        },
        {
          "title": "apple-samsung-dark",
          "createVideo": true,
          "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(32).jpg",
          "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(33).jpg",
          "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(34).jpg",
          "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(35).jpg"
        }
      ],
      "image_groups": [
        {
          "title": "apple-ios-light",
          "createVideo": false,
          "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(32).jpg",
          "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(33).jpg"
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

***

### CSV format

In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file.

Details for each data format are given in the sections below.

<Info>Encord supports up to 10,000 entries for upload in the CSV file.</Info>

<Warning>
  * Object URLs can't contain whitespace.
  * For backwards compatibility reasons, a single column CSV is supported. A file with the single `ObjectUrl` column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: "Expected a video, got a file of type XXX".
</Warning>

<AccordionGroup>
  <Accordion title="Videos">
    #### Videos

    A CSV file containing videos should contain two columns with the following mandatory column headings:\
    'ObjectURL' and 'Video title'. All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the video resource.

    * The 'Video title' column containing the `video_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Video title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.mp4 | Video 1     |
    | path/to/storage-location/frame2.mp4 | Video 2     |
    | path/to/storage-location/frame3.mp4 |             |
    | path/to/storage-location/frame4.mp4 | Video 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    A CSV file containing single images should contain two columns with the following mandatory headings:\
    'ObjectURL' and 'Image title'.  All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the image resource.

    * The 'Image title' column containing the `image_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Image title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.jpg | Image 1     |
    | path/to/storage-location/frame2.jpg | Image 2     |
    | path/to/storage-location/frame3.jpg |             |
    | path/to/storage-location/frame4.jpg | Image 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### Image groups

    A CSV file containing image groups should contain three columns with the following mandatory headings:\
    'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image group a file will be assigned to.

    In the example below the first two URLs are grouped together into 'Group 1', while the following two files are grouped together into 'Group 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Group 1           | false        |
    | path/to/storage-location/frame2.jpg | Group 1           | false        |
    | path/to/storage-location/frame3.jpg | Group 2           | false        |
    | path/to/storage-location/frame4.jpg | Group 2           | false        |

    <Note>Image groups do not require 'write' permissions.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### Image sequences

    A CSV file containing image sequences should contain three columns with the following mandatory headings: 'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.

    * The 'Create video' column. This can be left blank, as the default value is 'true'.

    In the example below the first two URLs are grouped together into 'Sequence 1', while the second two files are grouped together into 'Sequence 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |

    <Tip>Image groups and image sequences are only distinguished by the presence of the 'Create video' column.</Tip>

    <Note>Image sequences require 'write' permissions against your storage bucket to save the compressed video.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    A CSV file containing DICOM files should contain two columns with the following mandatory headings: 'ObjectURL' and 'Dicom title'. Both headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Series title' column containing the `dicom_title`. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.

    In the example below the first two files are grouped into 'dicom series 1', the next two files are grouped into 'dicom series 2', while the final file will remain separated as 'dicom series 3'.

    | ObjectUrl                           | Series title   |
    | ----------------------------------- | -------------- |
    | path/to/storage-location/frame1.dcm | dicom series 1 |
    | path/to/storage-location/frame2.dcm | dicom series 1 |
    | path/to/storage-location/frame3.dcm | dicom series 2 |
    | path/to/storage-location/frame4.dcm | dicom series 2 |
    | path/to/storage-location/frame5.dcm | dicom series 3 |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    #### Multiple file types

    You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.

    <Warning>Since the 'Create video' column defaults to `true` all files that **are not** image sequences must contain the value `false`</Warning>

    The example below shows a CSV file for the following:

    * Two image sequences composed of 2 files each.
    * One image group composed of 2 files.
    * One single image.
    * One video.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame5.jpg | Group 1           | false        |
    | path/to/storage-location/frame6.jpg | Group 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | path/to/storage-location/frame1.jpg | Image 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | full/storage/path/video.mp4         | Video 1           | false        |
  </Accordion>
</AccordionGroup>

***

## Step 4: Register Data with Encord

To use your data in Encord, it must be uploaded to the Encord **Files & Folders** storage. Once uploaded, your data can be reused across multiple Projects and contain no labels or annotations themselves. **Files & Folders** stores your data, while *Projects* store your labels. The following script creates a folder in **Files & Folders** and uses your AWS integration to register data in that folder.

The following script creates a new folder in **Files & Folders** and initiates uploads from AWS. It works for all file types.

<Tip>If `Upload is still in progress, try again later!` is returned, use the
[script to check the upload status](/sdk-documentation/getting-started-sdk/sdk-register-data-aws#step-5-check-data-upload) to see whether the upload has finished.</Tip>

Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<integration_title>` with the title of the integration you want to use.
* Replace `<folder_name>` with the folder name. The scripts assume that the specified folder name is unique.
* Replace `path/to/json/file.json` with the path to a [JSON file specifying which cloud storage files should be uploaded](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).
* Replace `A folder to store my files` with a meaningful description for your folder.
* Replace `"my": "folder_metadata"` with any metadata you want to add to the folder.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.
* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.
* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

<CodeGroup>
  ```python Create folder and register cloud data theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus  # Ensure correct import path

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

  # Specify the integration you want to use
  integrations = user_client.get_cloud_integrations()
  integration_idx = [i.title for i in integrations].index("<integration_title>")
  integration = integrations[integration_idx].id

  # Create a storage 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
  )

  # Initiate cloud data registration
  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
  )

  # Check upload status
  res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
  print(f"Execution result: {res}")

  if res.status == LongPollingStatus.PENDING:
      print("Upload is still in progress, try again later!")
  elif res.status == LongPollingStatus.DONE:
      print("Upload completed")
      if res.unit_errors:
          print("The following URLs failed to upload:")
          for e in res.unit_errors:
              print(e.object_urls)
  else:
      print(f"Upload failed: {res.errors}")

  ```

  ```Example output theme={"dark"}
  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.
  ```
</CodeGroup>

***

### Step 5: Check Registration Status

If Step 5 returns `"Upload is still in progress, try again later!"`, run the following code to query the Encord server again. Ensure that you replace `<upload_job_id>` with the output by the previous code. In the example above upload\_job\_id=`c4026edb-4fw2-40a0-8f05-a1af7f465727`.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.

* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.

* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

```python theme={"dark"}
# Import dependencies
from uuid import UUID
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus
from encord.storage import StorageFolder 

upload_job_id = "<upload_job_id>"
folder_id = "<folder_uuid>" 

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

# Get the storage folder by ID
storage_folder = user_client.get_storage_folder(UUID(folder_id))

# Check upload status
res = storage_folder.add_private_data_to_folder_get_result(
    upload_job_id=UUID(upload_job_id),
    timeout_seconds=30,
)
print(f"Execution result: {res}")

if res.status == LongPollingStatus.PENDING:
    print("Upload is still in progress, try again later!")
elif res.status == LongPollingStatus.DONE:
    print("Upload completed")
    if res.unit_errors:
        print("The following URLs failed to upload:")
        for e in res.unit_errors:
            print(e.object_urls)
else:
    print(f"Upload failed: {res.errors}")
```

<Tip>Omitting the `timeout_seconds` argument from the
[add\_private\_data\_to\_dataset\_get\_result()](/sdk-documentation/sdk-references/dataset#add-private-data-to-dataset-get-result) method performs status checks until the status upload has finished.</Tip>

***

## Step 6: Create a Dataset

<Note>Creating a Dataset and adding files to a Dataset are two distinct steps. [Click here](/sdk-documentation/index-sdk/sdk-add-files-to-datasets) to learn how to add data to an existing Dataset.</Note>

<Info>Datasets cannot be deleted using the SDK or the API. Use the Encord platform to delete Datasets. </Info>

The following example creates a Dataset called “Houses” that expects data hosted on Azure blob.

* Substitute `<private_key_path>` with the file path for your private key.
* Replace "Houses" with the name you want your Dataset to have.

<CodeGroup>
  ```python Example code theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import StorageLocation

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

  # Create a new dataset
  dataset = user_client.create_dataset(
      dataset_title="Houses",
      dataset_type=StorageLocation.AZURE,
      create_backing_folder=False,
  )

  # Prints a CreateDatasetResponse object. Verify the Dataset creation
  print(dataset_response)

  # Print the storage location
  print(f"Using storage location: AZURE")
  ```

  ```python Example output theme={"dark"}
  {
  {'title': 'Houses', 'type': 3, 'dataset_hash': 'd2bbbaed-cf33-4583-81b5-f30691abde1d', 'user_hash': 'iaDJxNNrMuQMtFPcP9oszw2OCHm2', 'backing_folder_uuid': UUID('5f8364e8-8ccd-4f9f-9066-91e055da920d')}
  }
  ```
</CodeGroup>

***

## Step 7: Add Your Data to a Dataset

Now that you registered your data and created a Dataset, it is time to add your files to the Dataset. The following scripts add all files in a specified folder to a Dataset.

* Replace `<private_key_path>` with the path to your private key.
* Replace `<folder_name>` with the name you want to give your Storage folder.
* Replace `<dataset_hash>` with the hash of the Dataset you want to add the data units to.

<Note>Files added to the folder at a later time **will not** be automatically added to the Dataset.</Note>

```python All files theme={"dark"}
from encord import EncordUserClient

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1))

dataset = user_client.get_dataset("<dataset_hash>")

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List all data units
    items = list(storage_folder.list_items())

    # Collect all item UUIDs
    item_uuids = [item.uuid for item in items]

    # Output the retrieved data units
    for item in items:
        print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")

    # Link all items at once if there are any
    if item_uuids:
        dataset.link_items(item_uuids)
else:
    print("Folder not found.")
```

***

## Step 8: Verify Your Files Are in the Dataset

After adding your files to the Dataset, verify that all the files you expect to be there made it into the Dataset.

The following script prints the URLs of all the files in a Dataset. Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<dataset_hash>` with the hash of your Dataset.

```python Sample Code theme={"dark"}
#Import dependencies
from encord import EncordUserClient, Project,Dataset
from encord.objects.project import ProjectDataset
from encord.orm.dataset import DatasetAccessSettings

#Initiate client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

#Files the file links to all files in the Dataset
dataset_level_file_links = []
dataset: Dataset = user_client.get_dataset("<dataset_hash>")
for data in dataset.list_data_rows():
    dataset_level_file_links.append(data.file_link)
print(dataset_level_file_links)
```

***

## Step 9: Prepare Your Data for Label/Annotation Import

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/sdk-documentation/getting-started-sdk/sdk-get-started-ontology">
      Prepare Data for Labels
    </a>
  </div>
</>

***

## Step 10: Import Labels/Annotations

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual">
      Import Labels/Annotations
    </a>
  </div>
</>


# Register GCP Data (SDK)
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-register-data-gcp



Before you can do anything with the Encord platform and cloud storage, you need to configure your cloud storage to work with Encord. Once the integration between Encord and your cloud storage is complete, you can then use your data in Encord.

<Note>
  Registering your cloud data with Encord only references the files. **Your data is not stored on Encord servers**.
</Note>

There are two parts to setting up a GCP integration in Encord:

1. Setting up a GCP bucket on the [Google Cloud Platform](https://console.cloud.google.com) so that it can be integrated with Encord. This includes setting up a CORS configuration for your bucket.

2. Creating a GCP integration on the Encord platform: [https://app.encord.com/integrations](https://app.encord.com/integrations) or [https://app.us.encord.com/integrations](https://app.us.encord.com/integrations).

<Tip>See our [GCP integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration) for a detailed guide to setting up an integration.</Tip>

## Step 1: Setup GCP Integration

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration#1-setting-up-a-gcp-bucket">
      Step 1: Setup GCP bucket
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-gcp-integration#creating-a-cors-configuration">
      Step 2: Configure CORS
    </a>
  </div>
</>

## Step 2: Create Encord Integration

Once your GCP storage is set up and configured, you are ready to create the integration in the Encord platform ([https://app.encord.com/integrations](https://app.encord.com/integrations) or [https://app.us.encord.com/integrations](https://app.us.encord.com/integrations)).

In the *Integrations* section of the Encord platform, click **+New integration** to create a new integration.

<div>
  <img />
</div>

Click **+ Add integration**.

Create the integration by selecting *GCP* at the top of the chooser. Enter a name for the integration, and enter the name of the bucket you wish to make available in the second dropdown of the GCP integration window.

<div>
  <img />
</div>

Optionally check the box to enable **Strict client-only access, server-side media features will not be available** if you would like Encord to sign URLs, but refrain from downloading any media files onto Encord servers. Read more about this feature [here](/platform-documentation/General/annotate-data-integrations#strict-client-only-access).

<div>
  <img />
</div>

Click **Create** to create the GCP integration.

## Step 3: Create JSON or CSV for Registration

All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

<Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data)</Note>

<Info>Encord supports file names up to 300 characters in length for any file or video for upload.</Info>

<Info>
  Encord enforces the following upload limits for each JSON file used for file registration:

  * Up to 1 million URLs
  * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  * URLs can be up to 16 KB in size

  Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
</Info>

<Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

### Create JSON file for Registration

For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

<Note>If `skip_duplicate_urls` is set to `true`, all object URLs that exactly match existing images/videos in the dataset are skipped.</Note>

***

<AccordionGroup>
  <Accordion title="Videos">
    #### [Videos](#videos)

    **Video Metadata**

    When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

    <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "cloud-path-to-your-video-1"
          },
          {
            "objectUrl": "cloud-path-to-your-video-2",
              "videoMetadata": {
                "fps": frames-per-second,
                "duration": duration-in-seconds,
                "width": frame-width,
                "height": frame-height,
                "file_size": file-size-in-bytes,
                "mime_type": "MIME-file-type-extension"
              }
            }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/eLeopardJog.mp4"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/_video.mp4"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/bluemlisalphutte_flyover.mp4"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake_normalized.mp4"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/boat_lake.MP4"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/snow_sled.MOV"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/cyclists.MP4"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Video Metadata theme={"dark"}
      {
          "videos": [
            {
              "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/video_file.mp4",
              "videoMetadata": {
                  "fps": 23.98,
                  "duration": 29.09,
                  "width": 1280,
                  "height": 720,
                  "file_size": 5468354,
                  "mime_type": "video/mp4"
              }
            }
          ],
          "skip_duplicate_urls": true
        }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Audio files">
    #### [Audio Files](#audio-files)

    The following is an example JSON file for uploading two audio files to Encord.

    <Tip>
      Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
    </Tip>

    * Example 1 imports audio files with an Encord title.
    * Example 2 imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "audio": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-custom-audio-file-title.mp3"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Audio Metadata theme={"dark"}
      {
          "audio": [
            {
              "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/audio_file.mp3",
              "audioMetadata": {
                  "duration": 23.98,
                  "file_size": 2900000,
                  "mime_type": "audio/mp3",
                  "sample_rate": 44100,
                  "bit_depth": 24,
                  "codec": "mp3",
                  "num_channels": 2
              }
            }
          ],
          "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="PDFs">
    #### [PDFs](#pdfs)

    The following are example JSON files for uploading PDFs to Encord.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-document-02.pdf"
          },
          {
            "objectUrl": "<object url_3>",
            "title": "my-document-03.pdf",
            "pdfMetadata": {
              "fileSize": 300,
              "numPages": 5
              }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "pdfs": [
            {
              "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-01.pdf",

            },
            {
              "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-02.pdf",
              "title": "my-document-02.pdf"
            },
            {
              "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-document-03.pdf",
              "title": "my-document-03.pdf",
              "pdfMetadata": {
                "fileSize": 300,
                "numPages": 5
                }
            }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Text Files">
    #### [Text Files](#text-files)

    The following are example JSON files for uploading text files to Encord.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-file.html"
          },
          {
            "objectUrl": "<object url_3>",
            "title": "my-plain-text-file.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "<object url_4>",
            "title": "my-csv-file.csv",
            "textMetadata": {
              "fileSize": 250,
              "mime_type": "text/csv"
            }
          },
          {
            "objectUrl": "<object url_5>",
            "title": "my-xml-file.xml",
            "textMetadata": {
              "fileSize": 300,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "<object url_6>",
            "title": "my-html-file.html",
            "textMetadata": {
              "fileSize": 400,
              "mime_type": "text/html"
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "text": [
            {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-file-01.html"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-01.txt",
            "title": "my-plain-text-file-01.txt"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-plain-text-file-02.txt",
            "title": "my-plain-text-file-02.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-csv-file-01.csv",
            "title": "my-csv-file-01.csv",
            "textMetadata": {
              "fileSize": 250,
              "mime_type": "text/csv"
            }
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-xml-file-01.xml",
            "title": "my-xml-file-01.xml",
            "textMetadata": {
              "fileSize": 300,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/my-html-file-01.html",
            "title": "my-html-file-01.html",
            "textMetadata": {
              "fileSize": 400,
              "mime_type": "text/html"
            }
          }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    #### [Single Images](#single-images)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    The JSON structure for single images parallels that of videos.

    **Template:** Provides the proper JSON format to import images into Encord.

    **Examples:**

    * **Data** Imports the images only.

    * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/images/file-name-01.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-02.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-03.file-extension",
            "title": "image-title.file-extension"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/es/0001.jpg"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/0003.jpg"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
          },
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/large_images/pexels-ivo-rainha-00057.png"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Image Metadata theme={"dark"}

      {
        "images": [
          {
            "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/my_image.jpg",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### [Image groups](#image-groups)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image groups are collections of images that are processed as one annotation task.
    * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
    * Image groups do NOT require 'write' permissions to your cloud storage.
    * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the image groups only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "image_groups": [
          {
            "title": "<title 1>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
          },
          {
            "title": "<title 2>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Image group 01",
            "createVideo": false,
            "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/0001.jpg",
            "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/0002.jpg",
            "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
          },
          {
            "title": "Image group 02",
            "createVideo": false,
            "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0001.jpg",
            "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-0002.jpg",
            "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-0003.jpg"
          }
        ],
        "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### [Image sequences](#image-sequences)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image sequences are collections of images that are processed as one annotation task and represented as a video.
    * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
    * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
    * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
    * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

    <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the images groups only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "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>"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Image sequence 001",
            "createVideo": true,
            "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/01.jpg",
            "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/02.jpg",
            "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/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://storage.cloud.google.com/encord-image-bucket/images/thing-01.jpg",
            "objectUrl_1": "<https://storage.cloud.google.com/encord-image-bucket/images/thing-02.jpg",
            "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/thing-03.jpg"
          }
        ],
        "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    #### [DICOM](#dicom)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Each `dicom_series` element can contain one or more DICOM series.
    * Each series requires a title and at least one object URL, as shown in the example below.
    * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

    <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

    The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

    * The first series contains only a single object URL, as it is composed of a single file.
    * The second series contains 3 object URLs, as it is composed of three separate files.
    * The third series contains 2 object URLs, as it is composed of two separate files.

    <Info>
      For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
    </Info>

    ```json JSON for DICOM theme={"dark"}
    {
      "dicom_series": [
        {
          "title": "Series-1",
          "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series1-file.dcm"
        },
        {
          "title": "Series-2",
          "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file1.dcm",
          "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file2.dcm",
          "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file3.dcm",
        },
          {
          "title": "Series-3",
          "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file1.dcm",
          "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file2.dcm",
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="NIfTI">
    #### [NIfTI](#nifti)

    The following is an example JSON file for uploading two NIfTI files to Encord.

    ```json theme={"dark"}
    {
        "nifti": [
          {
            "title": "<file-1>",
            "objectUrl": "https://my-bucket/.../nifti-file1.nii"
          },
          {
            "title": "<file-2>",
            "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
          }
        ],
        "skip_duplicate_urls": true
      }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

    ```json Multiple file types theme={"dark"}

    {
      "images": [
        {
          "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/Image1.png"
        }
      ],
      "videos": [
        {
          "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Cooking.mp4"
        },
        {
          "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Oranges.mp4"
        }
      ],
      "image_groups": [
        {
          "title": "apple-samsung-light",
          "createVideo": true,
          "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/1+(32).jpg",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
          "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
          "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
        },
        {
          "title": "apple-samsung-dark",
          "createVideo": true,
          "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/2+(32).jpg",
          "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/2+(33).jpg",
          "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/2+(34).jpg",
          "objectUrl_3": "https://storage.cloud.google.com/encord-image-bucket/images/2+(35).jpg"
        }
      ],
      "image_groups": [
        {
          "title": "apple-ios-light",
          "createVideo": false,
          "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/3+(32).jpg",
          "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/3+(33).jpg"
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

***

### Create CSV File for Registration

In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file.

Details for each data format are given in the sections below.

<Info>Encord supports up to 10,000 entries for upload in the CSV file.</Info>

<Warning>
  * Object URLs can't contain whitespace.
  * For backwards compatibility reasons, a single column CSV is supported. A file with the single `ObjectUrl` column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: "Expected a video, got a file of type XXX".
</Warning>

<AccordionGroup>
  <Accordion title="Videos">
    #### Videos

    A CSV file containing videos should contain two columns with the following mandatory column headings:\
    'ObjectURL' and 'Video title'. All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the video resource.

    * The 'Video title' column containing the `video_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Video title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.mp4 | Video 1     |
    | path/to/storage-location/frame2.mp4 | Video 2     |
    | path/to/storage-location/frame3.mp4 |             |
    | path/to/storage-location/frame4.mp4 | Video 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    A CSV file containing single images should contain two columns with the following mandatory headings:\
    'ObjectURL' and 'Image title'.  All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the image resource.

    * The 'Image title' column containing the `image_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Image title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.jpg | Image 1     |
    | path/to/storage-location/frame2.jpg | Image 2     |
    | path/to/storage-location/frame3.jpg |             |
    | path/to/storage-location/frame4.jpg | Image 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### Image groups

    A CSV file containing image groups should contain three columns with the following mandatory headings:\
    'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image group a file will be assigned to.

    In the example below the first two URLs are grouped together into 'Group 1', while the following two files are grouped together into 'Group 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Group 1           | false        |
    | path/to/storage-location/frame2.jpg | Group 1           | false        |
    | path/to/storage-location/frame3.jpg | Group 2           | false        |
    | path/to/storage-location/frame4.jpg | Group 2           | false        |

    <Note>Image groups do not require 'write' permissions.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### Image sequences

    A CSV file containing image sequences should contain three columns with the following mandatory headings: 'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.

    * The 'Create video' column. This can be left blank, as the default value is 'true'.

    In the example below the first two URLs are grouped together into 'Sequence 1', while the second two files are grouped together into 'Sequence 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |

    <Tip>Image groups and image sequences are only distinguished by the presence of the 'Create video' column.</Tip>

    <Note>Image sequences require 'write' permissions against your storage bucket to save the compressed video.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    A CSV file containing DICOM files should contain two columns with the following mandatory headings: 'ObjectURL' and 'Dicom title'. Both headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Series title' column containing the `dicom_title`. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.

    In the example below the first two files are grouped into 'dicom series 1', the next two files are grouped into 'dicom series 2', while the final file will remain separated as 'dicom series 3'.

    | ObjectUrl                           | Series title   |
    | ----------------------------------- | -------------- |
    | path/to/storage-location/frame1.dcm | dicom series 1 |
    | path/to/storage-location/frame2.dcm | dicom series 1 |
    | path/to/storage-location/frame3.dcm | dicom series 2 |
    | path/to/storage-location/frame4.dcm | dicom series 2 |
    | path/to/storage-location/frame5.dcm | dicom series 3 |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    #### Multiple file types

    You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.

    <Warning>Since the 'Create video' column defaults to `true` all files that **are not** image sequences must contain the value `false`</Warning>

    The example below shows a CSV file for the following:

    * Two image sequences composed of 2 files each.
    * One image group composed of 2 files.
    * One single image.
    * One video.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame5.jpg | Group 1           | false        |
    | path/to/storage-location/frame6.jpg | Group 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | path/to/storage-location/frame1.jpg | Image 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | full/storage/path/video.mp4         | Video 1           | false        |
  </Accordion>
</AccordionGroup>

***

## Step 4: Register Data with Encord

To use your data in Encord, it must be uploaded to the Encord **Files & Folders** storage. Once uploaded, your data can be reused across multiple Projects and contain no labels or annotations themselves. **Files & Folders** stores your data, while *Projects* store your labels. The following script creates a folder in **Files & Folders** and uses your AWS integration to register data in that folder.

The following script creates a new folder in **Files & Folders** and initiates uploads from AWS. It works for all file types.

<Tip>If `Upload is still in progress, try again later!` is returned, use the
[script to check the upload status](/sdk-documentation/getting-started-sdk/sdk-register-data-aws#step-5-check-data-upload) to see whether the upload has finished.</Tip>

Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<integration_title>` with the title of the integration you want to use.
* Replace `<folder_name>` with the folder name. The scripts assume that the specified folder name is unique.
* Replace `path/to/json/file.json` with the path to a [JSON file specifying which cloud storage files should be uploaded](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).
* Replace `A folder to store my files` with a meaningful description for your folder.
* Replace `"my": "folder_metadata"` with any metadata you want to add to the folder.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.
* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.
* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

<CodeGroup>
  ```python Create folder and register cloud data theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus  # Ensure correct import path

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

  # Specify the integration you want to use
  integrations = user_client.get_cloud_integrations()
  integration_idx = [i.title for i in integrations].index("<integration_title>")
  integration = integrations[integration_idx].id

  # Create a storage 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
  )

  # Initiate cloud data registration
  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
  )

  # Check upload status
  res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
  print(f"Execution result: {res}")

  if res.status == LongPollingStatus.PENDING:
      print("Upload is still in progress, try again later!")
  elif res.status == LongPollingStatus.DONE:
      print("Upload completed")
      if res.unit_errors:
          print("The following URLs failed to upload:")
          for e in res.unit_errors:
              print(e.object_urls)
  else:
      print(f"Upload failed: {res.errors}")

  ```

  ```Example output theme={"dark"}
  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.
  ```
</CodeGroup>

***

### Step 5: Check Registration Status

If Step 5 returns `"Upload is still in progress, try again later!"`, run the following code to query the Encord server again. Ensure that you replace `<upload_job_id>` with the output by the previous code. In the example above upload\_job\_id=`c4026edb-4fw2-40a0-8f05-a1af7f465727`.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.

* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.

* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

```python theme={"dark"}
# Import dependencies
from uuid import UUID
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus
from encord.storage import StorageFolder 

upload_job_id = "<upload_job_id>"
folder_id = "<folder_uuid>" 

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

# Get the storage folder by ID
storage_folder = user_client.get_storage_folder(UUID(folder_id))

# Check upload status
res = storage_folder.add_private_data_to_folder_get_result(
    upload_job_id=UUID(upload_job_id),
    timeout_seconds=30,
)
print(f"Execution result: {res}")

if res.status == LongPollingStatus.PENDING:
    print("Upload is still in progress, try again later!")
elif res.status == LongPollingStatus.DONE:
    print("Upload completed")
    if res.unit_errors:
        print("The following URLs failed to upload:")
        for e in res.unit_errors:
            print(e.object_urls)
else:
    print(f"Upload failed: {res.errors}")
```

<Tip>Omitting the `timeout_seconds` argument from the
[add\_private\_data\_to\_dataset\_get\_result()](/sdk-documentation/sdk-references/dataset#add-private-data-to-dataset-get-result) method performs status checks until the status upload has finished.</Tip>

***

## Step 6: Create a Dataset

<Note>Creating a Dataset and adding files to a Dataset are two distinct steps. [Click here](/sdk-documentation/index-sdk/sdk-add-files-to-datasets) to learn how to add data to an existing Dataset.</Note>

<Info>Datasets cannot be deleted using the SDK or the API. Use the Encord platform to delete Datasets. </Info>

The following example creates a Dataset called “Houses” that expects data hosted on GCP.

* Substitute `<private_key_path>` with the file path for your private key.
* Replace "Houses" with the name you want your Dataset to have.

<CodeGroup>
  ```python Example code theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import StorageLocation

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

  # Create a new dataset
  dataset = user_client.create_dataset(
      dataset_title="Houses",
      dataset_type=StorageLocation.GCP,
      create_backing_folder=False,
  )

  # Prints a CreateDatasetResponse object. Verify the Dataset creation
  print(dataset_response)

  # Print the storage location
  print(f"Using storage location: GCP")
  ```

  ```python Example output theme={"dark"}
  {
  {'title': 'Houses', 'type': 2, 'dataset_hash': 'd2bbbaed-cf33-4583-81b5-f30691abde1d', 'user_hash': 'iaDJxNNrMuQMtFPcP9oszw2OCHm2', 'backing_folder_uuid': UUID('5f8364e8-8ccd-4f9f-9066-91e055da920d')}
  }
  ```
</CodeGroup>

***

## Step 7: Add Your Data to a Dataset

Now that you registered your data and created a Dataset, it is time to add your files to the Dataset. The following scripts add all files in a specified folder to a Dataset.

* Replace `<private_key_path>` with the path to your private key.
* Replace `<folder_name>` with the name you want to give your Storage folder.
* Replace `<dataset_hash>` with the hash of the Dataset you want to add the data units to.

<Note>Files added to the folder at a later time **will not** be automatically added to the Dataset.</Note>

```python All files theme={"dark"}
from encord import EncordUserClient

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1))

dataset = user_client.get_dataset("<dataset_hash>")

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List all data units
    items = list(storage_folder.list_items())

    # Collect all item UUIDs
    item_uuids = [item.uuid for item in items]

    # Output the retrieved data units
    for item in items:
        print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")

    # Link all items at once if there are any
    if item_uuids:
        dataset.link_items(item_uuids)
else:
    print("Folder not found.")
```

***

## Step 8: Verify Your Files Are in the Dataset

After adding your files to the Dataset, verify that all the files you expect to be there made it into the Dataset.

The following script prints the URLs of all the files in a Dataset. Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<dataset_hash>` with the hash of your Dataset.

```python Sample Code theme={"dark"}
#Import dependencies
from encord import EncordUserClient, Project,Dataset
from encord.objects.project import ProjectDataset
from encord.orm.dataset import DatasetAccessSettings

#Initiate client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

#Files the file links to all files in the Dataset
dataset_level_file_links = []
dataset: Dataset = user_client.get_dataset("<dataset_hash>")
for data in dataset.list_data_rows():
    dataset_level_file_links.append(data.file_link)
print(dataset_level_file_links)
```

***

## Step 9: Prepare Your Data for Label/Annotation Import

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/sdk-documentation/getting-started-sdk/sdk-get-started-ontology">
      Prepare Data for Labels
    </a>
  </div>
</>

***

## Step 10: Import Labels/Annotations

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual">
      Import Labels/Annotations
    </a>
  </div>
</>


# Register OTC Data (SDK)
Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-register-data-otc



Using cloud storage data in Encord is a multi-step process:

1. Set up your cloud storage so Encord can access your data

2. Create a cloud storage integration on Encord to link to your cloud storage

3. Create a JSON or CSV file to import your data

4. Create a Dataset

5. Perform the registration using the JSON or CSV file

## Step 1: Setup OTC Integration

Before you can do anything with the Encord platform and cloud storage, you need to configure your cloud storage to work with Encord. Once the integration between Encord and your cloud storage is complete, you can then use your data in Encord.

In order to integrate with Open Telecom Cloud, you need to:

1. Create the account which accesses data in the Object Storage Service.
2. Give the account read access to the desired buckets by:
   1. Creating a Custom Bucket Policy.
   2. (Optional) If you have *Cross-origin resource sharing (CORS)* configured on your buckets, make sure that `*.encord.com` is given read access.
3. Create the integration by giving Encord access to that account's credentials.

<Tip>See our [OTC integration documentation](/platform-documentation/General/annotate-data-integrations/annotate-otc-integration) for a detailed guide to setting up an OTC integration.</Tip>

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/platform-documentation/General/annotate-data-integrations/annotate-otc-integration#1-create-the-account">
      Step 1: Create Account
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-otc-integration#creating-a-custom-bucket-policy">
      Step 2: Give Read access
    </a>

    <a href="/platform-documentation/General/annotate-data-integrations/annotate-otc-integration#3-optional-configuring-cors">
      Step 3: Configure CORS
    </a>
  </div>
</>

## Step 2: Create Encord Integration

On the Encord platform enter the `Access key ID` and `Secret access key`, which should be located in the access key file, generated with the creation of the user. *(if the access key has been misplaced, a new one can be created from the IAM User menu)*.

<img />

Optionally check the box to enable **Strict client-only access, server-side media features will not be available** if you would like Encord to sign URLs, but refrain from downloading any media files onto Encord servers. Read more about this feature [here](/platform-documentation/General/annotate-data-integrations#strict-client-only-access).

<div>
  <img />
</div>

Finally, click the **Create** button at the bottom of the pop-up. The integration will now appear in the list of integrations in the 'Integrations' tab.

## Step 3: Create JSON or CSV for Registration

All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

<Note>For a list of supported file formats for each data type, go [here](/platform-documentation/General/general-supported-data)</Note>

<Info>Encord supports file names up to 300 characters in length for any file or video for upload.</Info>

<Info>
  Encord enforces the following upload limits for each JSON file used for file registration:

  * Up to 1 million URLs
  * A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  * URLs can be up to 16 KB in size

  Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
</Info>

<Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (`clientMetadata`) to specify key frames, custom metadata, and custom embeddings. For more information go [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata) or [here for information on using the SDK](/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata).</Tip>

### Create JSON file for Registration

For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

<Note>If `skip_duplicate_urls` is set to `true`, all object URLs that exactly match existing images/videos in the dataset are skipped.</Note>

***

<AccordionGroup>
  <Accordion title="Videos">
    #### [Videos](#videos)

    **Video Metadata**

    When the `videoMetadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

    <Warning>To guarantee accurate labels, it is crucial that the `videoMetadata` provided is accurate.</Warning>

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "cloud-path-to-your-video-1"
          },
          {
            "objectUrl": "cloud-path-to-your-video-2",
              "videoMetadata": {
                "fps": frames-per-second,
                "duration": duration-in-seconds,
                "width": frame-width,
                "height": frame-height,
                "file_size": file-size-in-bytes,
                "mime_type": "MIME-file-type-extension"
              }
            }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/og.mp4"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/blue_bus_video.mp4"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/bluemlisalphutte_flyover.mp4"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake_normalized.mp4"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/boat_lake.MP4"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/snow_sled.MOV"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/cyclists.MP4"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Video Metadata theme={"dark"}
      {
          "videos": [
            {
              "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/video_file.mp4",
              "videoMetadata": {
                  "fps": 23.98,
                  "duration": 29.09,
                  "width": 1280,
                  "height": 720,
                  "file_size": 5468354,
                  "mime_type": "video/mp4"
              }
            }
          ],
          "skip_duplicate_urls": true
        }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Audio files">
    #### [Audio Files](#audio-files)

    The following is an example JSON file for uploading two audio files to Encord.

    <Tip>
      Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
    </Tip>

    * **Template:**  Imports audio files with an Encord title.
    * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "audio": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-custom-audio-file-title.mp3"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Audio Metadata theme={"dark"}
      {
          "audio": [
            {
              "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/audio/audio_file.mp3",
              "audioMetadata": {
                  "duration": 23.98,
                  "file_size": 2900000,
                  "mime_type": "audio/mp3",
                  "sample_rate": 44100,
                  "bit_depth": 24,
                  "codec": "mp3",
                  "num_channels": 2
              }
            }
          ],
          "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="PDFs">
    #### [PDFs](#pdfs)

    The following are example JSON files for uploading PDFs to Encord.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-document-02.pdf"
          },
          {
            "objectUrl": "<object url_3>",
            "title": "my-document-03.pdf",
            "pdfMetadata": {
              "fileSize": 300,
              "numPages": 5
              }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "pdfs": [
            {
              "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-01.pdf",

            },
            {
              "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-02.pdf",
              "title": "my-document-02.pdf"
            },
            {
              "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-document-3.pdf",
              "title": "my-document-03.pdf",
              "pdfMetadata": {
                "fileSize": 300,
                "numPages": 5
                }
            }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Text Files">
    #### [Text Files](#text-files)

    The following are example JSON files for uploading text files to Encord.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-file.html"
          },
          {
            "objectUrl": "<object url_3>",
            "title": "my-plain-text-file.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "<object url_4>",
            "title": "my-csv-file.csv",
            "textMetadata": {
              "fileSize": 250,
              "mime_type": "text/csv"
            }
          },
          {
            "objectUrl": "<object url_5>",
            "title": "my-xml-file.xml",
            "textMetadata": {
              "fileSize": 300,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "<object url_6>",
            "title": "my-html-file.html",
            "textMetadata": {
              "fileSize": 400,
              "mime_type": "text/html"
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "text": [
            {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-file-01.html"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-01.txt",
            "title": "my-plain-text-file-01.txt"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-plain-text-file-02.txt",
            "title": "my-plain-text-file-02.txt",
            "textMetadata": {
              "fileSize": 200,
              "mime_type": "text/plain"
            }
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-csv-file-01.csv",
            "title": "my-csv-file-01.csv",
            "textMetadata": {
              "fileSize": 250,
              "mime_type": "text/csv"
            }
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-xml-file-01.xml",
            "title": "my-xml-file-01.xml",
            "textMetadata": {
              "fileSize": 300,
              "mime_type": "application/xml"
            }
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my-html-file-01.html",
            "title": "my-html-file-01.html",
            "textMetadata": {
              "fileSize": 400,
              "mime_type": "text/html"
            }
          }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    #### [Single Images](#single-images)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    The JSON structure for single images parallels that of videos.

    **Template:** Provides the proper JSON format to import images into Encord.

    **Examples:**

    * **Data** Imports the images only.

    * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/images/file-name-01.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-02.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-03.file-extension",
            "title": "image-title.file-extension"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0003.jpg"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
          },
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/large_images/pexels-ivo-rainha-00057.png"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Image Metadata theme={"dark"}

      {
        "images": [
          {
            "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/my_image.jpg",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### [Image groups](#image-groups)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image groups are collections of images that are processed as one annotation task.
    * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
    * Image groups do NOT require 'write' permissions to your cloud storage.
    * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image groups in the dataset are skipped.

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the image groups only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "image_groups": [
          {
            "title": "<title 1>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
          },
          {
            "title": "<title 2>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
            "clientMetadata": {"optional": "metadata"}
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Image group 01",
            "createVideo": false,
            "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0001.jpg",
            "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/0002.jpg",
            "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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 group 02",
            "createVideo": false,
            "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0001.jpg",
            "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0002.jpg",
            "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-0003.jpg"
          }
        ],
        "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### [Image sequences](#image-sequences)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image sequences are collections of images that are processed as one annotation task and represented as a video.
    * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
    * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
    * Each object in the `image_groups` array with the `createVideo` flag set to `true` represents a single image sequence.
    * If `skip_duplicate_urls` is set to `true`, all URLs exactly matching existing image sequences in the dataset are skipped.

    <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `true`. Both use the key `image_groups`.</Tip>

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the images groups only.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "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>"
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Image sequence 001",
            "createVideo": true,
            "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/01.jpg",
            "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/02.jpg",
            "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.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-bucket.obs.eu-de.otc.t-systems.com/images/thing-01.jpg",
            "objectUrl_1": "<https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-02.jpg",
            "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/thing-03.jpg"
          }
        ],
        "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    #### [DICOM](#dicom)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Each `dicom_series` element can contain one or more DICOM series.
    * Each series requires a title and at least one object URL, as shown in the example below.
    * If `skip_duplicate_urls` is set to `true`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

    <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

    The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

    * The first series contains only a single object URL, as it is composed of a single file.
    * The second series contains 3 object URLs, as it is composed of three separate files.
    * The third series contains 2 object URLs, as it is composed of two separate files.

    <Info>
      For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
    </Info>

    ```json JSON for DICOM theme={"dark"}
    {
      "dicom_series": [
        {
          "title": "Series-1",
          "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series1-file.dcm"
        },
        {
          "title": "Series-2",
          "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file1.dcm",
          "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file2.dcm",
          "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file3.dcm",
        },
          {
          "title": "Series-3",
          "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file1.dcm",
          "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file2.dcm",
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="NIfTI">
    #### [NIfTI](#nifti)

    The following is an example JSON file for uploading two NIfTI files to Encord.

    ```json theme={"dark"}
    {
        "nifti": [
          {
            "title": "<file-1>",
            "objectUrl": "https://my-bucket/.../nifti-file1.nii"
          },
          {
            "title": "<file-2>",
            "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
          }
        ],
        "skip_duplicate_urls": true
      }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

    ```json Multiple file types theme={"dark"}

    {
      "images": [
        {
          "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/Image1.png"
        }
      ],
      "videos": [
        {
          "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Cooking.mp4"
        },
        {
          "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Oranges.mp4"
        }
      ],
      "image_groups": [
        {
          "title": "apple-samsung-light",
          "createVideo": true,
          "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(32).jpg",
          "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(33).jpg",
          "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(34).jpg",
          "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(35).jpg"
        },
        {
          "title": "apple-samsung-dark",
          "createVideo": true,
          "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(32).jpg",
          "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(33).jpg",
          "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(34).jpg",
          "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(35).jpg"
        }
      ],
      "image_groups": [
        {
          "title": "apple-ios-light",
          "createVideo": false,
          "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(32).jpg",
          "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(33).jpg"
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

***

### Create CSV File for Registration

In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file.

Details for each data format are given in the sections below.

<Info>Encord supports up to 10,000 entries for upload in the CSV file.</Info>

<Warning>
  * Object URLs can't contain whitespace.
  * For backwards compatibility reasons, a single column CSV is supported. A file with the single `ObjectUrl` column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: "Expected a video, got a file of type XXX".
</Warning>

<AccordionGroup>
  <Accordion title="Videos">
    #### Videos

    A CSV file containing videos should contain two columns with the following mandatory column headings:\
    'ObjectURL' and 'Video title'. All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the video resource.

    * The 'Video title' column containing the `video_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Video title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.mp4 | Video 1     |
    | path/to/storage-location/frame2.mp4 | Video 2     |
    | path/to/storage-location/frame3.mp4 |             |
    | path/to/storage-location/frame4.mp4 | Video 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    A CSV file containing single images should contain two columns with the following mandatory headings:\
    'ObjectURL' and 'Image title'.  All headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the image resource.

    * The 'Image title' column containing the `image_title`. If left blank, the original file name is used.

    In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

    | ObjectUrl                           | Image title |
    | ----------------------------------- | ----------- |
    | path/to/storage-location/frame1.jpg | Image 1     |
    | path/to/storage-location/frame2.jpg | Image 2     |
    | path/to/storage-location/frame3.jpg |             |
    | path/to/storage-location/frame4.jpg | Image 3     |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### Image groups

    A CSV file containing image groups should contain three columns with the following mandatory headings:\
    'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image group a file will be assigned to.

    In the example below the first two URLs are grouped together into 'Group 1', while the following two files are grouped together into 'Group 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Group 1           | false        |
    | path/to/storage-location/frame2.jpg | Group 1           | false        |
    | path/to/storage-location/frame3.jpg | Group 2           | false        |
    | path/to/storage-location/frame4.jpg | Group 2           | false        |

    <Note>Image groups do not require 'write' permissions.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### Image sequences

    A CSV file containing image sequences should contain three columns with the following mandatory headings: 'ObjectURL', 'Image group title', and 'Create video'. All three headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Image group title' column containing the `image_group_title`. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.

    * The 'Create video' column. This can be left blank, as the default value is 'true'.

    In the example below the first two URLs are grouped together into 'Sequence 1', while the second two files are grouped together into 'Sequence 2'.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |

    <Tip>Image groups and image sequences are only distinguished by the presence of the 'Create video' column.</Tip>

    <Note>Image sequences require 'write' permissions against your storage bucket to save the compressed video.</Note>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    A CSV file containing DICOM files should contain two columns with the following mandatory headings: 'ObjectURL' and 'Dicom title'. Both headings are case-insensitive.

    * The 'ObjectURL' column containing the `objectUrl`. This field is mandatory for each file, as it specifies the full URL of the resource.

    * The 'Series title' column containing the `dicom_title`. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.

    In the example below the first two files are grouped into 'dicom series 1', the next two files are grouped into 'dicom series 2', while the final file will remain separated as 'dicom series 3'.

    | ObjectUrl                           | Series title   |
    | ----------------------------------- | -------------- |
    | path/to/storage-location/frame1.dcm | dicom series 1 |
    | path/to/storage-location/frame2.dcm | dicom series 1 |
    | path/to/storage-location/frame3.dcm | dicom series 2 |
    | path/to/storage-location/frame4.dcm | dicom series 2 |
    | path/to/storage-location/frame5.dcm | dicom series 3 |
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    #### Multiple file types

    You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.

    <Warning>Since the 'Create video' column defaults to `true` all files that **are not** image sequences must contain the value `false`</Warning>

    The example below shows a CSV file for the following:

    * Two image sequences composed of 2 files each.
    * One image group composed of 2 files.
    * One single image.
    * One video.

    | ObjectUrl                           | Image group title | Create video |
    | ----------------------------------- | ----------------- | ------------ |
    | path/to/storage-location/frame1.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame2.jpg | Sequence 1        | true         |
    | path/to/storage-location/frame3.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame4.jpg | Sequence 2        | true         |
    | path/to/storage-location/frame5.jpg | Group 1           | false        |
    | path/to/storage-location/frame6.jpg | Group 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | path/to/storage-location/frame1.jpg | Image 1           | false        |
    | ObjectUrl                           | Image title       | Create video |
    | full/storage/path/video.mp4         | Video 1           | false        |
  </Accordion>
</AccordionGroup>

***

## Step 4: Register Data with Encord

To use your data in Encord, it must be uploaded to the Encord **Files & Folders** storage. Once uploaded, your data can be reused across multiple Projects and contain no labels or annotations themselves. **Files & Folders** stores your data, while *Projects* store your labels. The following script creates a folder in **Files & Folders** and uses your AWS integration to register data in that folder.

The following script creates a new folder in **Files & Folders** and initiates uploads from AWS. It works for all file types.

<Tip>If `Upload is still in progress, try again later!` is returned, use the
[script to check the upload status](/sdk-documentation/getting-started-sdk/sdk-register-data-aws#step-5-check-data-upload) to see whether the upload has finished.</Tip>

Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<integration_title>` with the title of the integration you want to use.
* Replace `<folder_name>` with the folder name. The scripts assume that the specified folder name is unique.
* Replace `path/to/json/file.json` with the path to a [JSON file specifying which cloud storage files should be uploaded](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).
* Replace `A folder to store my files` with a meaningful description for your folder.
* Replace `"my": "folder_metadata"` with any metadata you want to add to the folder.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.
* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.
* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

<CodeGroup>
  ```python Create folder and register cloud data theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus  # Ensure correct import path

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

  # Specify the integration you want to use
  integrations = user_client.get_cloud_integrations()
  integration_idx = [i.title for i in integrations].index("<integration_title>")
  integration = integrations[integration_idx].id

  # Create a storage 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
  )

  # Initiate cloud data registration
  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
  )

  # Check upload status
  res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
  print(f"Execution result: {res}")

  if res.status == LongPollingStatus.PENDING:
      print("Upload is still in progress, try again later!")
  elif res.status == LongPollingStatus.DONE:
      print("Upload completed")
      if res.unit_errors:
          print("The following URLs failed to upload:")
          for e in res.unit_errors:
              print(e.object_urls)
  else:
      print(f"Upload failed: {res.errors}")

  ```

  ```Example output theme={"dark"}
  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.
  ```
</CodeGroup>

***

### Step 5: Check Registration Status

If Step 5 returns `"Upload is still in progress, try again later!"`, run the following code to query the Encord server again. Ensure that you replace `<upload_job_id>` with the output by the previous code. In the example above upload\_job\_id=`c4026edb-4fw2-40a0-8f05-a1af7f465727`.

The script has several possible outputs:

* "Upload is still in progress, try again later!": The registration has not finished. Run this script again later to check if the data registration has finished.

* "Upload completed": The registration completed. If any files failed to upload, the URLs are listed.

* "Upload failed": The entire registration failed, and not just individual files. Ensure your [JSON file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format) is formatted correctly.

```python theme={"dark"}
# Import dependencies
from uuid import UUID
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus
from encord.storage import StorageFolder 

upload_job_id = "<upload_job_id>"
folder_id = "<folder_uuid>" 

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

# Get the storage folder by ID
storage_folder = user_client.get_storage_folder(UUID(folder_id))

# Check upload status
res = storage_folder.add_private_data_to_folder_get_result(
    upload_job_id=UUID(upload_job_id),
    timeout_seconds=30,
)
print(f"Execution result: {res}")

if res.status == LongPollingStatus.PENDING:
    print("Upload is still in progress, try again later!")
elif res.status == LongPollingStatus.DONE:
    print("Upload completed")
    if res.unit_errors:
        print("The following URLs failed to upload:")
        for e in res.unit_errors:
            print(e.object_urls)
else:
    print(f"Upload failed: {res.errors}")
```

<Tip>Omitting the `timeout_seconds` argument from the
[add\_private\_data\_to\_dataset\_get\_result()](/sdk-documentation/sdk-references/dataset#add-private-data-to-dataset-get-result) method performs status checks until the status upload has finished.</Tip>

***

## Step 6: Create a Dataset

<Note>Creating a Dataset and adding files to a Dataset are two distinct steps. [Click here](/sdk-documentation/index-sdk/sdk-add-files-to-datasets) to learn how to add data to an existing Dataset.</Note>

<Info>Datasets cannot be deleted using the SDK or the API. Use the Encord platform to delete Datasets. </Info>

The following example creates a Dataset called “Houses” that expects data hosted on OTC.

* Substitute `<private_key_path>` with the file path for your private key.
* Replace "Houses" with the name you want your Dataset to have.

<CodeGroup>
  ```python Example code theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import StorageLocation

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

  # Create a new dataset
  dataset = user_client.create_dataset(
      dataset_title="Houses",
      dataset_type=StorageLocation.OTC,
      create_backing_folder=False,
  )

  # Prints a CreateDatasetResponse object. Verify the Dataset creation
  print(dataset_response)

  # Print the storage location
  print(f"Using storage location: OTC")
  ```

  ```python Example output theme={"dark"}
  {
  {'title': 'Houses', 'type': 4, 'dataset_hash': 'd2bbbaed-cf33-4583-81b5-f30691abde1d', 'user_hash': 'iaDJxNNrMuQMtFPcP9oszw2OCHm2', 'backing_folder_uuid': UUID('5f8364e8-8ccd-4f9f-9066-91e055da920d')}
  }
  ```
</CodeGroup>

***

## Step 7: Add Your Data to a Dataset

Now that you registered your data and created a Dataset, it is time to add your files to the Dataset. The following scripts add all files in a specified folder to a Dataset.

* Replace `<private_key_path>` with the path to your private key.
* Replace `<folder_name>` with the name you want to give your Storage folder.
* Replace `<dataset_hash>` with the hash of the Dataset you want to add the data units to.

<Note>Files added to the folder at a later time **will not** be automatically added to the Dataset.</Note>

```python All files theme={"dark"}
from encord import EncordUserClient

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1))

dataset = user_client.get_dataset("<dataset_hash>")

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List all data units
    items = list(storage_folder.list_items())

    # Collect all item UUIDs
    item_uuids = [item.uuid for item in items]

    # Output the retrieved data units
    for item in items:
        print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")

    # Link all items at once if there are any
    if item_uuids:
        dataset.link_items(item_uuids)
else:
    print("Folder not found.")
```

***

## Step 8: Verify your files are in the Dataset

After adding your files to the Dataset, verify that all the files you expect to be there made it into the Dataset.

The following script prints the URLs of all the files in a Dataset. Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<dataset_hash>` with the hash of your Dataset.

```python Sample Code theme={"dark"}
#Import dependencies
from encord import EncordUserClient, Project,Dataset
from encord.objects.project import ProjectDataset
from encord.orm.dataset import DatasetAccessSettings

#Initiate client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

#Files the file links to all files in the Dataset
dataset_level_file_links = []
dataset: Dataset = user_client.get_dataset("<dataset_hash>")
for data in dataset.list_data_rows():
    dataset_level_file_links.append(data.file_link)
print(dataset_level_file_links)
```

***

## Step 9: Prepare Your Data for Label/Annotation Import

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/sdk-documentation/getting-started-sdk/sdk-get-started-ontology">
      Prepare Data for Labels
    </a>
  </div>
</>

***

## Step 10: Import Labels/Annotations

<>
  <meta />

  <meta name="viewport" />

  <title>Clickable Div</title>

  <div>
    <a href="/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual">
      Import Labels/Annotations
    </a>
  </div>
</>


# Import Custom Metadata (SDK)
Source: https://docs.encord.com/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata



Active and Index support filtering, creating Collections, and by extension, creating Datasets and Projects based on the custom metadata on your data.

## Prerequisites

Before you can filter your data or create a Collection based on your data's custom metadata, the custom metadata must exist in your Annotate Project.

<Note>This content applies to custom metadata (`clientMetadata`), which is the metadata associated with individual data units. This is distinct from `videoMetadata` that is used to specify video parameters when using [Strict client-only access](/platform-documentation/General/annotate-data-integrations#strict-client-only-access). It is also distinct from [patient metadata](/sdk-documentation/dicom-sdk/sdk-dicom-metadata) in DICOM files.</Note>

Custom metadata (`clientMetadata`) is accessed by specifying the dataset using the \<dataset\_hash>. All Projects that have the specified Dataset attached contain custom metadata.

## READ THIS FIRST

While not required, we strongly recommend importing a metadata schema before importing custom metadata into Encord. The process we recommend:

1. [Import a metadata schema](/platform-documentation/Curate/custom-metadata/index-metadata-schema). If a metadata schema already exists, you can import metadata. You can run a small piece of code to verify that a metadata schema exists
2. Import your custom metadata.

<Note>Performing multiple schema imports overwrites the current schema with the new schema.</Note>

## Geospatial Custom Metadata

Geospatial custom metadata contains latitude and longitude information.

After importing geospatial custom metadata on your data units, you can filter data using a geospatial map in Index.

<Note>
  * Geospatial custom metadata is supported only in Index.

  * Geospatial custom metadata can be applied to all data unit types and on individual frames in videos.
</Note>

**Geospatial Format**

Latitude values fall between +90 (North) to -90 (South). Longitude values fall between +180 (West) to -180 (East).

<CodeGroup>
  ```json Boilerplate theme={"dark"}
  "clientMetadata": {
  "geo-point": {"latitude": +/- 90, "longitude": +/- 180}"
  }
  ```

  ```json Example 1 theme={"dark"}
  "clientMetadata": {
  "Coordinates": {"latitude": 0, "longitude": 51.4826}"
  }
  ```

  ```json Example 2 theme={"dark"}
  "clientMetadata": {
  "Coordinates": {"latitude": 44.30868, "longitude": −77.79486}"
  }
  ```
</CodeGroup>

## Import Custom Metadata

Importing custom metadata (clientMetadata) for any data type follows a similar format. But there are important differences for each data type.

<AccordionGroup>
  <Accordion title="Videos">
    #### [Videos](#videos)

    <Tip><b>BEST PRACTICE:</b> If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using key frames, custom metadata, and custom embeddings. When specifying key frames set the `sampling_rate` to `0`. This imports only the first frame and any key frames you specify in the video. This can significantly speed up the import of your data into Active and Index and help you to focus on only data you identify as critical.</Tip>

    The following table provides some guidance for the examples provided after the table.

    <table>
      <thead>
        <tr>
          <th>Title</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            Template
          </td>

          <td>Provides the proper JSON format to import videos into Encord.<br />This template provides examples from the most basic to the most complex.</td>
        </tr>

        <tr>
          <td>
            Data
          </td>

          <td>
            Imports videos into Encord.<br />

            *Why would I do this?*<br />

            * You ONLY want to add labels and classifications to your data.
            * You DO NOT want to use Index or Active.
          </td>
        </tr>

        <tr>
          <td>
            Key Frames
          </td>

          <td>
            Imports videos with an Encord title and specifies key frames (frames of interest) for Active and Index.<br />

            *Why would I do this?*<br />

            * You ONLY want to see frames that you deem critical in Active and Index.
            * You want to significantly improve the time to import videos into Active and Index.<br />

            `config` is optional when specifying key frames for Active and Index:<br />

            <Tip>Specifying a `sampling_rate` of `0` only imports the first frame and all key frames of your video into Active and Index.</Tip><br />

            ```json theme={"dark"}
            "config": {
              "sampling_rate": "<samples-per-second>",
              "keyframe_mode": "frame" or "seconds",
              },
            ```

            If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.
          </td>
        </tr>

        <tr>
          <td>
            Custom Metadata
          </td>

          <td>
            Imports videos with an Encord title, specifies key frames (frames of interest), and custom metadata for Active and Index.<br />

            *Why would I do this?*<br />

            * Importing custom metadata allows you to filter your data in Active and Index to make it easier to find the data you want to focus on. This speeds up creating Collections and by extension Datasets.
            * Specifying key frames means you ONLY want to see frames that you deem critical in Active and Index AND you want to significantly improve the time to import videos into Active and Index.<br />

            `config` is optional when specifying key frames for Active and Index:<br />

            <Tip>Specifying a `sampling_rate` of `0` only imports the first frame and all key frames of your video into Active and Index.</Tip><br />

            ```json theme={"dark"}
            "config": {
              "sampling_rate": "<samples-per-second>",
              "keyframe_mode": "frame" or "seconds",
              },
            ```

            If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.
          </td>
        </tr>

        <tr>
          <td>
            Embeddings
          </td>

          <td>
            Imports videos with an Encord title, specifies key frames (frames of interest), custom metadata, and custom embeddings for Active and Index. This example includes the following custom metadata types: boolean, varchar, datetime, uuid, number.<br />

            *Why would I do this?*<br />

            * Importing custom embeddings allows you to use scatter plots to examine your data AND allows you to use similarity search and natural language searches. Index supports embedding dimensions 1 to 4096, while Active supports embedding dimensions 1 to 2000.
            * Importing custom metadata allows you to filter your data in Active and Index to make it easier to find the data you want to focus on. This speeds up creating Collections and by extension Datasets.
            * Specifying key frames means you ONLY want to see frames that you deem critical in Active and Index AND you want to significantly improve the time to import videos into Active and Index.<br />

            `config` is optional when specifying custom embeddings for Active and Index:<br />

            <Tip>Specifying a `sampling_rate` of `0` only imports the first frame and all key frames of your video into Active and Index.</Tip><br />

            ```json theme={"dark"}
            "config": {
              "sampling_rate": "<samples-per-second>",
              "keyframe_mode": "frame" or "seconds",
              },
            ```

            If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.<br />

            <Tip>Refer to our documentation for more information about [data curation with Custom Metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata), [data curation with Custom Embeddings](/platform-documentation/Curate/custom-embeddings), and [label validation with Custom Embeddings](/platform-documentation/Validation/validation-custom-embeddings).</Tip>
          </td>
        </tr>

        <tr>
          <td>
            Video Metadata
          </td>

          <td>
            Imports videos with the `videoMetadata` flag. When the videoMetadata flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.
          </td>
        </tr>
      </tbody>
    </table>

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "videos": [
          {
            "objectUrl": "cloud-path-to-your-video-1",
            "title": "title-for-your-video-1",
            "clientMetadata": {
              "metadata-1": "value", 
              "metadata-2": "value",
              "geo-point": {"latitude": +/- 90, "longitude": +/- 180}
              }
          },
          {
            "objectUrl": "cloud-path-to-your-video-2",
            "title": "title-for-your-video-2",
            "clientMetadata": {
                "metadata-1": "value", 
                "metadata-2": "value",
                "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                "$encord": {
                    "frames": ["<frame-number-1>","<frame-number-2>","<frame-number-3>"]
                  }
              }
          },
          {
              "objectUrl": "cloud-path-to-your-video-3",
              "title": "title-for-your-video-3",
              "clientMetadata": {
                  "metadata-1": "value", 
                  "metadata-2": "value",
                  "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                  "$encord": {
                      "frames": {
                          "<frame-number-or-seconds>": {
                            "metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                            "<my-embedding>": [1.0, 2.0, 3.0]
                          },
                          "<frame-number-or-seconds>": {
                            "metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                            "<my-embedding>": [1.0, 2.0, 3.0]
                          }
                      }
                   }
                }
          },
          {
            "objectUrl": "cloud-path-to-your-video-4",
              "title": "title-for-your-video-4",
              "clientMetadata": {
                  "metadata-1": "value", 
                  "metadata-2": "value", 
                  "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                  "$encord": {
                      "config": {
                          "sampling_rate": "<samples-per-second>",
                          "keyframe_mode": "frame" or "seconds",
                      },
                      "frames": {
                          "<frame-number-or-seconds>": {
                            "metadata-1": "value", 
                            "metadata-2": "value",
                            "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                            "<my-embedding>": [1.0, 2.0, 3.0]
                          },
                          "<frame-number-or-seconds>": {
                            "metadata-1": "value", 
                            "metadata-2": "value",
                            "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                            "<my-embedding>": [1.0, 2.0, 3.0]
                          }
                      }
                  }
              }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Key Frames theme={"dark"}
      {
          "videos": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-001.mp4",
              "title": "Blueberries video 1",
                  "clientMetadata": {
                      "$encord": {
                          "frames": ["111", "113", "117", "119"]
                  }
              }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-002.mp4",
              "title": "Blueberries video 2",
              "clientMetadata": {
                  "clientMetadata": {
                      "$encord": {
                          "frames": ["111", "113", "117", "119"]
                       }
                   },
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-003.mp4",
              "title": "Blueberries video 3",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                          "frames": ["111", "113", "117", "119"]
                      }
                  }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cherries-001.MOV",
              "title": "Cherries video 1",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "3",
                              "keyframe_mode": "frame"
                          },
                          "frames": ["111", "113", "117", "119"]
                      }
                  }
            }
          ],
        "skip_duplicate_urls": true
        }
      ```

      ```json Metadata - Video theme={"dark"}
      {
          "videos": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-001.mp4",
              "title": "Blueberries video 1",
              "clientMetadata": {
                "Dark": True, "Location": "TX", "Date": "2021-01-11", "ACME Co ID": "32bb0e3a-018e-4ed6-b668-49d7564146aa", "Priority": "2", "Address": "Blackland Berry Farm, 230 Jones Rd, Royse City, TX 75189, United States", "Coordinates": {"latitude": -96.34177, "longitude": 32.88950}
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-002.mp4",
              "title": "Blueberries video 2",
              "clientMetadata": {
                "Dark": False, "Location": "IL", "Date": "2022-02-22", "ACME Co ID": "84617cec-f053-4d39-b554-218e486c56df", "Priority": "1", "Address": "McCann Berry Farm, 18110 Kishwaukee Valley Rd, Woodstock, IL 60098, United States", "Coordinates": {"latitude": 42.3147, "longitude": -88.4487}
              }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-003.mp4",
              "title": "Blueberries video 3",
                  "clientMetadata": {
                      "Dark": True, "Location": "OH", "Date": "2024-05-20", "ACME Co ID": "111b9455-d463-4f60-9239-15dc1bae5eb2", "Priority": "3", "Address": "The Blueberry Patch, 1285 W Hanley Rd, Mansfield, OH 44906, United States", "Coordinates": {"latitude": 40.6950, "longitude": -88.4487}
                      "$encord": {
                          "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                          "frames": ["111", "113", "117", "119"]
                      }
                  }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cherries-001.MOV",
              "title": "Cherries video 1",
                  "clientMetadata": {
                      "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
                      "$encord": {
                          "frames": ["111", "113", "117", "119"]
                      }
                  }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cherries-002.MP4",
              "title": "Cherries video 2",
                  "clientMetadata": {
                      "Dark": False, "Location": "FL", "Date": "2024-08-11", "ACME Co ID": "73689309-dfdc-4549-85f8-3302de9d30a4", "Priority": "0", "Address": "Cherry Lake Farm, 7836 Cherry Lake Rd. Groveland, FL 34736, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
                      "$encord": {
                          "config": {
                              "sampling_rate": "3",
                              "keyframe_mode": "frame"
                          },
                          "frames": ["111", "113", "117", "119"]
                      }
                  }
            }
          ],
        "skip_duplicate_urls": true
        }
      ```

      ```json Metadata - Key Frames theme={"dark"}
      {
          "videos": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-001.mp4",
              "title": "Blueberries video 1",
              "clientMetadata": {
                  "$encord": {
                    "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                      "frames": {
                          "111": {
                              "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0",
                              "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}
                              },
                          "113": {
                              "Dark": True, "Location": "CA", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b322-3c1fe2164d2f", "Priority": "1",
                              "Address": "Victoria Island Farms, 16021 CA-4, Holt, CA 95234, United States", "Coordinates": {"latitude": 37.9579, "longitude": -121.4629}
                          }
                        }
                    }
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-002.mp4",
              "title": "Blueberries video 2",
              "clientMetadata": {
                  "$encord": {
                      "frames": {
                          "111": {
                              "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}
                              },
                          "113": {
                              "Dark": True, "Location": "FL", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4542-b322-3c1fe2164d2f", "Priority": "1", "Address": "Cherry Lake Farm, 7836 Cherry Lake Rd. Groveland, FL 34736, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}
                          }
                        }
                    }
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-003.mp4",
              "title": "Blueberries video 3",
              "clientMetadata": {
                  "$encord": {
                    "config": {
                              "sampling_rate": "2",
                              "keyframe_mode": "frame"
                          },
                      "frames": {
                          "111": {
                              "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}
                              },
                          "113": {
                              "Dark": True, "Location": "CA", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4542-b333-3c1fe2164d2f", "Priority": "2", "Address": "Victoria Island Farms, 16021 CA-4, Holt, CA 95234, United States", "Coordinates": {"latitude": 37.9579, "longitude": -121.4629}
                          }
                        }
                    }
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cherries-001.MOV",
              "title": "Cherries video 1",
              "clientMetadata": {
                  "$encord": {
                    "Dark": True, "Location": "NY", "Date": "2024-03-19", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
                    "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                      "frames": {
                          "111": {
                              "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}
                              },
                          "113": {
                              "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}
                          }
                        }
                    }
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cherries-002.MP4",
              "title": "Cherries video 2",
              "clientMetadata": {
                  "$encord": {
                    "Dark": True, "Location": "CA", "Date": "2024-04-23", "ACME Co ID": "5309c30f-849e-44e9-b8f2-13da54d45a19", "Priority": "1", "Address": "Victoria Island Farms, 16021 CA-4, Holt, CA 95234, United States", "Coordinates": {"latitude": 37.9579, "longitude": -121.4629}
                    "config": {
                              "sampling_rate": "2",
                              "keyframe_mode": "frame"
                          },
                      "frames": {
                          "111": {
                              "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}
                              },
                          "113": {
                              "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}
                          }
                        }
                    }
                }
            }
          ],
        "skip_duplicate_urls": true
        }
      ```

      ```json Embeddings theme={"dark"}
      {
          "videos": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-001.mp4",
              "title": "Blueberries video 1",
              "clientMetadata": {
                  "$encord": {
                    "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                      "frames": {
                          "111": {
                              "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                          "113": {
                              "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                          }
                        }
                    }
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-002.mp4",
              "title": "Blueberries video 2",
              "clientMetadata": {
                  "$encord": {
                      "frames": {
                          "111": {
                              "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                          "113": {
                              "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                          }
                        }
                    }
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/blueberries-003.mp4",
              "title": "Blueberries video 3",
              "clientMetadata": {
                  "$encord": {
                    "config": {
                              "sampling_rate": "2",
                              "keyframe_mode": "frame"
                          },
                      "frames": {
                          "111": {
                              "embeddings-10": [0.44324257187793305, 0.22403790771089994, 0.2351464760810051, 0.3588273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                          "113": {
                              "embeddings-10": [0.8421826107513869, 0.33345671908774165, 0.3063308253882048, 0.037154463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                          }
                        }
                    }
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cherries-001.MOV",
              "title": "Cherries video 1",
              "clientMetadata": {
                  "$encord": {
                    "Dark": True, "Location": "NY", "Date": "2024-03-19", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
                    "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                      "frames": {
                          "111": {
                              "embeddings-10": [0.11824257187793305, 0.82303790771089994, 0.7391464760810051, 0.0128273275803421, 0.05299531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                          "113": {
                              "embeddings-10": [0.9421826107513869, 0.64745671908774165, 0.9873308253882048, 0.025754463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                          }
                        }
                    }
                }
            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/cherries-002.MP4",
              "title": "Cherries video 2",
              "clientMetadata": {
                  "$encord": {
                    "Dark": True, "Location": "CA", "Date": "2024-04-23", "ACME Co ID": "5309c30f-849e-44e9-b8f2-13da54d45a19", "Priority": "1", "Address": "Victoria Island Farms, 16021 CA-4, Holt, CA 95234, United States", "Coordinates": {"latitude": 37.9579, "longitude": -121.4629}
                    "config": {
                              "sampling_rate": "2",
                              "keyframe_mode": "frame"
                          },
                      "frames": {
                          "111": {
                            "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
                            "embeddings-10": [0.93524257187793305, 0.34903790771089994, 0.3001464760810051, 0.0221273275803421, 0.08469531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                          "113": {
                            "Dark": True, "Location": "NY", "Date": "2024-07-17", "ACME Co ID": "5275c4c7-693c-4541-b333-3c1fe2164d2f", "Priority": "0", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
                            "embeddings-10": [0.3211826107513869, 0.76545671908774165, 0.4373308253882048, 0.974754463823556754, 0.8855154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                          }
                        }
                    }
                }
            }
          ],
        "skip_duplicate_urls": true
        }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Audio files">
    #### [Audio Files](#audio-files)

    The following is an example JSON file for uploading two audio files to Encord.

    <Tip>
      Waveform generation for long audio files can cause lag. To avoid this, generate the waveform offline and upload it with the audio file. For more information go [here](/platform-documentation/Curate/index-audio#long-audio-files).
    </Tip>

    * **Template:** Imports audio files with an Encord title, and with custom metadata. Custom metadata only appears in the Encord UI in Active and Index as an option to filter your data.
    * **Audio Metadata:** Imports one audio file with the `audiometadata` flag. When the `audiometadata` flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "audio": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-custom-audio-file-title.mp3",
            "clientMetadata": {
              "optional_key_1": "optional_metadata_value_1",
              "geo-point": {"latitude": +/- 90, "longitude": +/- 180}
              }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Audio Metadata theme={"dark"}
      {
          "audio": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/audio_file.mp3",
              "audioMetadata": {
                  "duration": 23.98,
                  "file_size": 2900000,
                  "mime_type": "audio/mp3",
                  "sample_rate": 44100,
                  "bit_depth": 24,
                  "codec": "mp3",
                  "num_channels": 2
              }
            }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="PDFs">
    #### [PDFs](#pdfs)

    The following is an example JSON file for uploading PDFs to Encord.

    * **Template:** Imports PDFs with an Encord title, and with custom metadata. Custom metadata only appears in the Encord UI in Active and Index as an option to filter your data.
    * **Data:** Imports two PDFs with no title or custom metadata.
    * **Custom Metadata:** Imports two pdfs with a title and custom metadata.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "pdfs": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-file.html",
            "clientMetadata": {
              "optional_key_1": "optional_metadata_value_1",
              "geo-point": {"latitude": +/- 90, "longitude": +/- 180}}
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "pdfs": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-01.pdf",

            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-02.pdf",

            }
          ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Custom Metadata theme={"dark"}
      {
          "pdfs": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-001.pdf",
            "title": "my-document-001.pdf",
            "clientMetadata": {
              "Author": "Alex Smith", 
              "Doc Type": "Internal - Critical"
              }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-document-002.pdf",
            "title": "my-document-002.pdf",
            "clientMetadata": {
              "Author": "Chris Wong", 
              "Doc Type": "Public"
              }
          }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Text Files">
    #### [Text Files](#text-files)

    The following is an example JSON file for uploading text files to Encord.

    * **Template:** Imports text files with an Encord title, and with custom metadata. Custom metadata only appears in the Encord UI in Active and Index as an option to filter your data.
    * **Data:** Imports two text files with no title or custom metadata.
    * **Custom Metadata:** Imports two text files with a title and custom metadata.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "text": [
          {
            "objectUrl": "<object url_1>"
          },
          {
            "objectUrl": "<object url_2>",
            "title": "my-file.html",
            "clientMetadata": {
              "optional_key_1": "optional_metadata_value_1",
              "geo-point": {"latitude": +/- 90, "longitude": +/- 180}
              }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}
      {
          "text": [
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-file-01.html",

            },
            {
              "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-file-02.xml",

            }
          ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Custom Metadata theme={"dark"}
      {
          "text": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-file-001.html",
            "title": "my-document-001.pdf",
            "clientMetadata": {
              "Author": "Alex Smith", 
              "Doc Type": "Internal - Critical"
              }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/pdfs/my-file-002.xml",
            "title": "my-document-002.pdf",
            "clientMetadata": {
              "Author": "Chris Wong", 
              "Doc Type": "Public"
              }
          }
          ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Single images">
    #### [Single Images](#single-images)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    The JSON structure for single images parallels that of videos.

    **Template:** Provides the proper JSON format to import images into Encord.

    **Examples:**

    * **Data** Imports the images only.

    * **Custom Metadata:** Imports images with an Encord title for the images and with custom metadata for each image. Custom metadata only appears in Active and Index as an option to filter your data. This example includes the following custom metadata types: boolean, varchar, datetime, uuid, number.

    * **Embeddings:** Imports images with an Encord title, custom metadata, and custom embeddings for each image. This example includes the following custom metadata types: boolean, varchar, datetime, uuid, number.

    * **Image Metadata:** Imports images with image metadata. This improves the import speed for your images.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/images/file-name-01.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-02.file-extension"
          },
          {
            "objectUrl": "file/path/to/images/file-name-03.file-extension",
            "title": "image-title.file-extension",
            "clientMetadata": {
              "metadata-1": "value", 
              "metadata-2": "value",
              "geo-point": {"latitude": +/- 90, "longitude": +/- 180}
              }
          },
          {
            "objectUrl": "file/path/to/images/file-name-04.file-extension",
            "title": "image-title.file-extension",
            "clientMetadata": {
              "metadata-1": "value", 
              "metadata-2": "value",
              "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
              "<my-embedding>": [1.0, 2.0, 3.0]
            }
           }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data    theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.jpg"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0003.jpg"
          },
          {
            "objectUrl": "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"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/DALL%C2%B7E+2022-12-08+22.16.52+-+steampunk+combustion+engine+that+is+fueled+by+data+and+produces+computer+vision+algorithms.png"
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/large_images/pexels-ivo-rainha-00057.png"
          }
        ]
      }
      ```

      ```json Custom Metadata theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-0001.jpg",
            "title": "Blueberry 0001",
            "clientMetadata": {"Dark": False, "Location": "OH", "Date": "2022-04-21", "ACME Co ID": "1649db48-6917-42e4-843a-1dce773d8196", "Priority": "3", "Address": "The Blueberry Patch, 1285 W Hanley Rd, Mansfield, OH 44906, United States", "Coordinates": {"latitude": 40.6950, "longitude": -88.4487}}
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-0002.jpg",
            "title": "Blueberry 0002",
            "clientMetadata": {"Dark": True, "Location": "TX", "Date": "2021-02-03", "ACME Co ID": "be8ec507-3173-4109-b858-1b122b9dc68d", "Priority": "1" "Address": "Blackland Berry Farm, 230 Jones Rd, Royse City, TX 75189, United States", "Coordinates": {"latitude": -96.34177, "longitude": 32.88950}}
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-0001.jpg",
            "title": "Blueberry 0003",
            "clientMetadata": {"Dark": True, "Location": "IL", "Date": "2024-04-23", "ACME Co ID": "6b3601aa-893a-4b62-b2d4-40f146c1ef30", "Priority": "2", "Address": "McCann Berry Farm, 18110 Kishwaukee Valley Rd, Woodstock, IL 60098, United States", "Coordinates": {"latitude": 42.3147, "longitude": -88.4487}}
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-0001.jpg",
            "title": "Cherry 0001",
            "clientMetadata": {"Dark": True, "Location": "CA", "Date": "2024-04-23", "ACME Co ID": "f8acd1bd-53e2-4aa7-937b-a6f0ce18f030", "Priority": "2", "Address": "Victoria Island Farms, 16021 CA-4, Holt, CA 95234, United States", "Coordinates": {"latitude": 37.9579, "longitude": -121.4629}}
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-0002.jpg",
            "title": "Cherry 0002",
            "clientMetadata": {"Dark": False, "Location": "CA", "Date": "2024-04-23", "ACME Co ID": "e3dd8e31-d98d-49ec-93af-5814ba0d3725", "Priority": "2", "Address": "Victoria Island Farms, 16021 CA-4, Holt, CA 95234, United States", "Coordinates": {"latitude": 37.9579, "longitude": -121.4629}}
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-0003.jpg",
            "title": "Cherry 0003",
            "clientMetadata": {"Dark": False, "Location": "OH", "Date": "2024-04-23", "ACME Co ID": "54fc4f1b-48b1-4c9a-897a-57859dae8a50", "Priority": "1", "Address": "The Blueberry Patch, 1285 W Hanley Rd, Mansfield, OH 44906, United States", "Coordinates": {"latitude": 40.6950, "longitude": -88.4487}}
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Embeddings theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 01",
            "clientMetadata": {
              "embeddings-10": [
                0.44931257187793305, 
                0.11303790771089994, 
                0.9001464760810051, 
                0.2798273275803421, 
                0.06879531104035541, 
                0.8275038481160373, 
                0.9419277893526817, 
                0.7294979532997635, 
                0.18146276890284674, 
                0.07504156777630822
                ]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-02.jpg",
            "title": "Blueberry 02",
            "clientMetadata": {
              "embeddings-10": [
                0.44531257187793305, 
                0.22303790771089994, 
                0.1101464760810051, 
                0.3898273275803421, 
                0.06879531104035541, 
                0.8275038481160373, 
                0.9419277893526817, 
                0.7294979532997635, 
                0.18146276890284674, 
                0.07504156777630822
                ]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 03",
            "clientMetadata": {
              "embeddings-10": [
                0.45631257187793305, 
                0.23403790771089994, 
                0.1211464760810051, 
                0.3678273275803421, 
                0.06849531104035541, 
                0.8275038481160373, 
                0.9419277893526817, 
                0.7294979532997635, 
                0.18146276890284674, 
                0.07504156777630822
                ]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-01.jpg",
            "title": "Cherry 01",
            "clientMetadata": {
              "Dark": False, 
              "Location": "NY", 
              "Date": "2024-06-13", 
              "ACME Co ID": "8ada6567-c034-4bd4-91d0-04dab5d729d5", 
              "Priority": "1",
              "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
              "embeddings-10": [
                0.67831257187793305, 
                0.32603790771089994, 
                0.4341464760810051, 
                0.9748273275803421, 
                0.23549531104035541, 
                0.8275038481160373, 
                0.9419277893526817, 
                0.7294979532997635, 
                0.18146276890284674, 
                0.07504156777630822
                ]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-02.jpg",
            "title": "Cherry 02",
            "clientMetadata": {
              "Dark": False, 
              "Location": "NY", 
              "Date": "2024-06-13", 
              "ACME Co ID": "1262bf57-402e-427c-8c60-276df65513ea", 
              "Priority": "1",
              "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
              "embeddings-10": [
                0.42531257187793305, 
                0.33403790771089994, 
                0.5671464760810051, 
                0.3688273275803421, 
                0.06849531104035541, 
                0.8275038481160373, 
                0.9419277893526817, 
                0.7294979532997635, 
                0.18146276890284674, 
                0.07504156777630822
                ]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-03.jpg",
            "title": "Cherry 03",
            "clientMetadata": {
              "Dark": True, 
              "Location": "OH", 
              "Date": "2024-06-13", 
              "ACME Co ID": "3000919f-01e2-4574-a4fd-a2790c4f7b8b", 
              "Priority": "2",
              "Address": "The Blueberry Patch, 1285 W Hanley Rd, Mansfield, OH 44906, United States", "Coordinates": {"latitude": 40.6950, "longitude": -88.4487},
              "embeddings-10": [
                0.22231257187793305, 
                0.44503790771089994, 
                0.7341464760810051, 
                0.8368273275803421, 
                0.06849531104035541, 
                0.8275038481160373, 
                0.9419277893526817, 
                0.7294979532997635, 
                0.18146276890284674, 
                0.07504156777630822
                ]
                }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Image Metadata theme={"dark"}

      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/my_image.jpg",
            "imageMetadata": {
              "mimeType": "image/jpg",
              "fileSize": 124,
              "width": 640,
              "height": 480
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image groups">
    #### [Image groups](#image-groups)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image groups are collections of images that are processed as one annotation task.
    * Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
    * Image groups do NOT require 'write' permissions to your cloud storage.
    * Custom metadata is defined per image group, not per image. See our documentation [here](/platform-documentation/Curate/custom-metadata/import-custom-metadata#add-custom-metadata-to-images-in-an-image-group) to learn how to add `clientMetadata` to images in an image group.
    * If `skip_duplicate_urls` is set to `True`, all URLs exactly matching existing image groups in the dataset are skipped.

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the image groups only.

    * **Custom Metadata:** Imports image groups with an Encord title for the image groups and with custom metadata for each image. Custom metadata only appears in Active and Index as an option to filter your data. This example includes the following custom metadata types: boolean, varchar, datetime, uuid, number.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "image_groups": [
          {
            "title": "<title 1>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
          },
          {
            "title": "<title 2>",
            "createVideo": false,
            "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
            "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
            "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
            "clientMetadata": {
              "optional": "metadata",
              "geo-point": {"latitude": +/- 90, "longitude": +/- 180}
              }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Data theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Image group 01",
            "createVideo": false,
            "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0001.jpg",
            "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/0002.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 group 02",
            "createVideo": false,
            "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0001.jpg",
            "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0002.jpg",
            "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-0003.jpg"
          }
        ],
        "skip_duplicate_urls": true
      }

      ```

      ```json Custom Metadata theme={"dark"}

      {
        "image_groups": [
          {
            "title": "Blueberries image group 1",
            "createVideo": false,
            "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-0001.jpg",
            "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-0002.jpg",
            "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-0003.jpg",
            "clientMetadata": {"Dark": False, "Location": "TX", "Date": "2024-05-07", "ACME Co ID": "22adb044-5cc9-43ba-a063-0f0efd5a76ca", "Priority": "0", "Address": "Blackland Berry Farm, 230 Jones Rd, Royse City, TX 75189, United States", "Coordinates": {"latitude": -96.34177, "longitude": 32.88950}}
          },
          {
            "title": "Cherries image group 1",
            "createVideo": false,
            "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-0001.jpg",
            "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-0002.jpg",
            "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-0003.jpg",
            "clientMetadata": {"Dark": True, "Location": "OH", "Date": "2024-05-07", "ACME Co ID": "0d4633c3-ef5f-4bf1-bf84-8f2dc2250f3d", "Priority": "1", "Address": "The Blueberry Patch, 1285 W Hanley Rd, Mansfield, OH 44906, United States", "Coordinates": {"latitude": 40.6950, "longitude": -88.4487}}
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Image sequences">
    #### [Image sequences](#image-sequences)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Image sequences are collections of images that are processed as one annotation task and represented as a video.
    * Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
    * Creating Image sequences from cloud storage requires 'write' permissions, as new files have to be created in order to be read as a video.
    * Each object in the `image_groups` array with the `createVideo` flag set to `True` represents a single image sequence.
    * Custom client metadata is defined per image sequence, not per image.
    * If `skip_duplicate_urls` is set to `True`, all URLs exactly matching existing image sequences in the dataset are skipped.

    <Tip> The only difference between adding image groups and image sequences using a JSON file is that image sequences require the `createVideo` flag to be set to `True`. Both use the key `image_groups`.</Tip>

    <Note>The position of each image within the sequence needs to be specified in the key (`objectUrl_{position_number}`).</Note>

    <Info>Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.</Info>

    **Template:** Provides the proper JSON format to import image groups into Encord.

    **Examples:**

    * **Data:** Imports the images groups only.

    * **Custom Metadata:** Imports image groups and custom metadata. This example includes the following custom metadata types: boolean, varchar, datetime, uuid, number.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "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 Data theme={"dark"}

      {
        "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 Custom Metadata theme={"dark"}

      {
        "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
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DICOM">
    #### [DICOM](#dicom)

    For detailed information about the JSON file format used for import go [here](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).

    * Each `dicom_series` element can contain one or more DICOM series.
    * Each series requires a title and at least one object URL, as shown in the example below.
    * If `skip_duplicate_urls` is set to `True`, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

    <Note>Custom metadata is distinct from patient metadata, which is included in the `.dcm` file and does not have to be specific during the upload to Encord. </Note>

    The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

    * The first series contains only a single object URL, as it is composed of a single file.
    * The second series contains 3 object URLs, as it is composed of three separate files.
    * The third series contains 2 object URLs, as it is composed of two separate files.

    <Info>
      For each DICOM upload, an additional `DicomSeries` file is created. This file represents the series file-set. Only `DicomSeries` are displayed in the Encord application.
    </Info>

    ```json Template theme={"dark"}
    {
      "dicom_series": [
        {
          "title": "Series-1",
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series1-file.dcm"
        },
        {
          "title": "Series-2",
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file1.dcm",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file2.dcm",
          "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file3.dcm",
        },
          {
          "title": "Series-3",
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file1.dcm",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file2.dcm",
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="NIfTI">
    #### [NIfTI](#nifti)

    The following is an example JSON file for uploading two NIfTI files to Encord.

    ```json Template theme={"dark"}
    {
        "nifti": [
          {
            "title": "<file-1>",
            "objectUrl": "https://my-bucket/.../nifti-file1.nii"
          },
          {
            "title": "<file-2>",
            "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
          }
        ],
        "skip_duplicate_urls": true
      }

    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title=" Multiple file types ">
    You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

    ```json Multiple file types theme={"dark"}

    {
      "images": [
        {
          "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/Image1.png"
        }
      ],
      "videos": [
        {
          "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Cooking.mp4"
        },
        {
          "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Oranges.mp4"
        }
      ],
      "image_groups": [
        {
          "title": "apple-samsung-light",
          "createVideo": True,
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(32).jpg",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
          "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
          "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
        },
        {
          "title": "apple-samsung-dark",
          "createVideo": True,
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(32).jpg",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(33).jpg",
          "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(34).jpg",
          "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(35).jpg"
        }
      ],
      "image_groups": [
        {
          "title": "apple-ios-light",
          "createVideo": false,
          "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(32).jpg",
          "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(33).jpg"
        }
      ],
      "skip_duplicate_urls": true
    }

    ```
  </Accordion>
</AccordionGroup>

### Import to Files already in Index

<Tip>We recommend importing custom metadata when you import your data, because importing with your data can significantly save you time when importing at scale. However, you can import custom metadata on data that already exists in Encord.</Tip>

**Importing with Custom Embeddings**

You can import custom embeddings with custom metadata. When importing custom embeddings with custom metadata keep the following in mind:

`config` is optional when importing your custom embeddings:

```json theme={"dark"}
"config": {
    "sampling_rate": "<samples-per-second>",
    "keyframe_mode": "frame" or "seconds",
},
```

If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

<Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video into Index.</Info>

**Examples**

<CodeGroup>
  ```python Boilerplate theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.http.bundle import Bundle
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  updates = {

      # Imports custom metadata 
      "<data-hash-1>": {"metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180}},
      "<data-hash-2>": {"metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180}},

      # Imports custom metadata and specifies key frames for Active and Index
      "<data-hash-3>": {
          "metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
          "$encord": {
              "frames": {"111", "113", "117", "119"}
              }
      },

      # Imports custom metadata and specifies key frames, custom metadata on frames, and the custom embeddings for those key frames
      "<data-hash-3>": {
          "metadata-1": "value", "metadata-2": "value",
          "$encord": {
              "frames": {
                  "<frame-number-or-seconds>": {
                    "metadata-1": "value", "metadata-2": "value",
                    "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                    "<my-embedding>": [1.0, 2.0, 3.0]
                      },
                  "<frame-number-or-seconds>": {
                    "metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                    "<my-embedding>": [1.0, 2.0, 3.0]
                      }
                  }
              }
      },

      # Imports custom metadata and specifies key frames and the custom embeddings for those key frames
      "<data-hash-4>": {
          "metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
          "$encord": {
              "config": {
                  "sampling_rate": <samples-per-second>,  # VIDEO ONLY (optional default = 1 sample/second)
                  "keyframe_mode": "frame" or "seconds",  # VIDEO ONLY (optional default = "frame")
              },
              "frames": {
                  "<frame-number-or-seconds>": {
                    "metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                      "<my-embedding>": [1.0, 2.0, 3.0]
                      },
                  "<frame-number-or-seconds>": {
                    "metadata-1": "value", "metadata-2": "value", "geo-point": {"latitude": +/- 90, "longitude": +/- 180},
                      "<my-embedding>": [1.0, 2.0, 3.0]
                      }
                  }
              }
          }
      },
  }

  # Use the Bundle context manager
  with Bundle() as bundle:
      # Update the storage items based on the dictionary
      for item_uuid, metadata_update in updates.items():
          item = user_client.get_storage_item(item_uuid=item_uuid)

          # Make a copy of the current metadata and update it with the new metadata
          curr_metadata = item.client_metadata.copy()
          curr_metadata.update(metadata_update)

          # Update the item with the new metadata and bundle
          item.update(client_metadata=curr_metadata, bundle=bundle)
  ```

  ```python Example - Simple theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.http.bundle import Bundle
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

  # Authentication
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  updates = {

      # Imports the following custom metadata types: boolean, varchar, datetime, uuid, number 
      "f2155fa4-6040-408a-84d5-72bacb4f45db": {"Dark": True, "Location": "NY", "Date": "2024-02-20", "ACME Co ID": "876b1bfb-c911-459f-9f54-2dc89d53ac06", "Priority": "1", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}},

      # Imports the following custom metadata types: boolean, varchar, datetime, uuid, number
      "f235ad84-f9eb-4dc1-934d-d05e1cd70e59": {"Dark": True, "Location": "NY", "Date": "2024-02-20", "ACME Co ID": "876b1bfb-c911-459f-9f54-2dc89d53ac06", "Priority": "1", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484}}
  }

  # Use the Bundle context manager
  with Bundle() as bundle:
      # Update the storage items based on the dictionary
      for item_uuid, metadata_update in updates.items():
          item = user_client.get_storage_item(item_uuid=item_uuid)

          # Make a copy of the current metadata and update it with the new metadata
          curr_metadata = item.client_metadata.copy()
          curr_metadata.update(metadata_update)

          # Update the item with the new metadata and bundle
          item.update(client_metadata=curr_metadata, bundle=bundle)

  ```

  ```python Example - Advanced theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.http.bundle import Bundle
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

  # Authentication
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  updates = {

      # Imports the following custom metadata types: boolean, varchar, datetime, uuid, number
      # Only imports key frames and the custom embeddings for those key frames
      "6b8d797a-4655-43c3-b251-cbd6cc995bc6": {
          "clientMetadata": {
              "Dark": True, "Location": "NY", "Date": "2022-12-22", "ACME Co ID": "c1012905-b8d9-4119-9cc3-6a92c7bcfbef", "Priority": "3", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
              "$encord": {
                  "config": {
                      "sampling_rate": "0",
                      "keyframe_mode": "frame"
                  },
                  "frames": {
                      "111": {
                        "Dark": True, "Location": "NY", "Date": "2022-12-22", "ACME Co ID": "c1012905-b8d9-4119-9cc3-6a92c7bcfbef", "Priority": "2", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
                        "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                          },
                      "113": {
                        "Dark": True, "Location": "CA", "Date": "2022-12-22", "ACME Co ID": "c1012905-b8d9-4119-9cc3-6a92c7bcfbef", "Priority": "3",
                        "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                          }
                  }
              }
          }
      },

      # Imports the following custom metadata types: boolean, varchar, datetime, uuid, number
      # Samples for Active and Index at 4 FPS and key frames and the custom embeddings for those key frames
      "d9185f6e-3dbc-443b-bd37-77b2f34f157e": {
          "clientMetadata": {
              "Dark": False, "Location": "IL", "Date": "2020-11-21", "ACME Co ID": "8b896cb8-14cd-4cdd-8cfa-1603e725b22d", "Priority": "1", "Address": "McCann Berry Farm, 18110 Kishwaukee Valley Rd, Woodstock, IL 60098, United States", "Coordinates": {"latitude": 42.3147, "longitude": -88.4487}
              "$encord": {
                  "config": {
                      "sampling_rate": "4",
                      "keyframe_mode": "frame"
                  },
                  "frames": {
                      "11": {
                        "Dark": True, "Location": "NY", "Date": "2022-12-22", "ACME Co ID": "c1012905-b8d9-4119-9cc3-6a92c7bcfbef", "Priority": "3", "Address": "The Chatham Berry Farm, 2309 New York 203, Chatham, NY 12037, United States", "Coordinates": {"latitude": 42.36425, "longitude": -73.59484},
                        "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                      },
                      "13": {
                        "Dark": True, "Location": "CA", "Date": "2022-12-22", "ACME Co ID": "c1012905-b8d9-4119-9cc3-6a92c7bcfbef", "Priority": "2",
                        "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                      }
                  }
              }
          }
      }
  }

  # Use the Bundle context manager
  with Bundle() as bundle:
      # Update the storage items based on the dictionary
      for item_uuid, metadata_update in updates.items():
          item = user_client.get_storage_item(item_uuid=item_uuid)

          # Make a copy of the current metadata and update it with the new metadata
          curr_metadata = item.client_metadata.copy()
          curr_metadata.update(metadata_update)

          # Update the item with the new metadata and bundle
          item.update(client_metadata=curr_metadata, bundle=bundle)
  ```
</CodeGroup>

## Folders and Custom Metadata

### List custom metadata (Folders)

<CodeGroup>
  ```python Boilerplate theme={"dark"}

  from encord import EncordUserClient
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

  # Authentication
  SSH_PATH = "<file-path-to-ssh-private-key-file>"
  FOLDER_HASH = "<unique-folder-id>"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  folder = user_client.get_storage_folder(FOLDER_HASH)
  items = folder.list_items()

  for item in items:
      print (item.uuid, item.client_metadata)

  ```

  ```python Example theme={"dark"}

  from encord import EncordUserClient
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

  # Authentication
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  FOLDER_HASH = "2a838557-d6f4-4408-a980-64246dc5c56b"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  folder = user_client.get_storage_folder(FOLDER_HASH)
  items = folder.list_items()

  for item in items:
      print (item.uuid, item.client_metadata)

  ```
</CodeGroup>

### Import Custom Metadata (Folders)

<Tip>
  Before importing custom metadata to Encord, [first import a metadata schema](#import-metadata-schema).
  We strongly recommend that you upload your custom metadata to Folders, instead of importing using Datasets. Importing custom metadata to data in folders allows you to filter your data in Index by custom metadata.
</Tip>

<Info>After importing or updating custom metadata, verify that your custom metadata (list the data units with custom metadata) applied correctly. Do not simply add a `print` command after importing or updating your custom metadata.</Info>

#### Import custom metadata to specific data units in a Folder

This code allows you to import custom metadata on specific data units in Index. This code OVERWRITES all existing custom metadata on a data unit.

<CodeGroup>
  ```python Boilerplate theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy


  # Authentication
  SSH_PATH = "<file-path-to-ssh-private-key-file>"
  FOLDER_HASH = "<unique-folder-id>"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  folder = user_client.get_storage_folder(FOLDER_HASH)

  # Define a dictionary with item UUIDs and their respective metadata updates
  updates = {
      # "<data-unit-id>": {"metadata": "metadata-value"},
      # "<data-unit-id>": {"metadata": False},
      # "<data-unit-id>": {"metadata": "metadata-value"},
      # "<data-unit-id>": {"metadata": True}
  }

  # Update the storage items based on the dictionary
  for item_uuid, metadata in updates.items():
      item = user_client.get_storage_item(item_uuid=item_uuid)
      item.update(client_metadata=metadata)

  ```

  ```python Example 1 theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

  # Authentication
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  FOLDER_HASH = "2a838557-d6f4-4408-a980-64246dc5c56b"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  folder = user_client.get_storage_folder(FOLDER_HASH)

  # Define a dictionary with item UUIDs and their respective metadata updates
  updates = {
      # "<data-unit-id>": {"metadata": "metadata-value"},
      # "<data-unit-id>": {"metadata": False}, # examples
      "8ad58157-ca74-4ae4-8f37-a0193430bcac": {"dark": True},
      "f165fe81-1956-4347-81ca-3a3b198f3f23": {"light": False},
      "9bd58157-ca74-4ae4-8f37-a0193431bcba": {"count": "100"},
      "62daaa33-195e-4faf-be5b-8335a239beb6": {"taken_at": "2024-02-24"}
  }

  # Update the storage items based on the dictionary
  for item_uuid, metadata in updates.items():
      item = user_client.get_storage_item(item_uuid=item_uuid)
      item.update(client_metadata=metadata)

  ```
</CodeGroup>

#### Import custom metadata to all data units in a Folder

This code allows you to update ALL custom metadata on ALL data units in a Folder in Index. This code OVERWRITES all existing custom metadata on a data unit.

<CodeGroup>
  ```python Boilerplate theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

  # Authentication
  SSH_PATH = "<file-path-to-ssh-private-key-file>"
  FOLDER_HASH = "<unique-folder-id>"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  folder = user_client.get_storage_folder(FOLDER_HASH)
  items = folder.list_items()

  for item in items:
       item.update(client_metadata={"metadata": "value", "metadata": "value"})
  ```

  ```python Example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

  # Authentication
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  FOLDER_HASH = "2a838557-d6f4-4408-a980-64246dc5c56b"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  folder = user_client.get_storage_folder(FOLDER_HASH)
  items = folder.list_items()

  for item in items:
       item.update(client_metadata={"dark": True, "captured_at": "2024-02-24"})
  ```
</CodeGroup>

#### Update custom metadata

The *Specific Data Units* code enables you to update custom metadata for specific data units in Index. It does not overwrite all existing custom metadata on a data unit. Instead, it updates metadata that matches existing keys with new values and adds any new custom metadata keys to the data unit without affecting other existing metadata.

The *All data units in a Project* code updates the custom metadata for all data units in the specified Project. Replace the `client_metadata` with the metadata you want to update.

<CodeGroup>
  ```python Specific data units in Index theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  # Authentication
  SSH_PATH = "<private_key_path>"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  # Define a dictionary with item UUIDs and their respective metadata updates
  updates = {
       "<data-unit-id>": {"metadata": "metadata-value"},
       "<data-unit-id>": {"metadata": False},
       "<data-unit-id>": {"metadata": "metadata-value"},
      # "<data-unit-id>": {"metadata": True}
  }

  # Update the storage items based on the dictionary
  for item_uuid, metadata_update in updates.items():
      item = user_client.get_storage_item(item_uuid=item_uuid)

      # make a copy of the current metadata and update it with the new metadata
      curr_metadata = item.client_metadata.copy()
      curr_metadata.update(metadata_update)

      # update the item with the new metadata
      item.update(client_metadata=curr_metadata)
  ```

  ```python All data units in a Project theme={"dark"}
  #Import dependencies
  from encord.user_client import EncordUserClient

  # Authentication
  SSH_PATH = "<private_key_path>"

  # Authenticate with Encord using the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(SSH_PATH)

  # Specify a Project
  project = user_client.get_project("<project_hash>")

  for label_row in project.list_label_rows_v2():
      storage_item = user_client.get_storage_item(label_row.backing_item_uuid)

      # Updates the specified client_metadata for all items in the Project.
      storage_item.update(client_metadata={"my": "new dict"})
  ```
</CodeGroup>

#### Bulk import custom metadata to all data units in a Folder

This code allows you to update custom metadata on all data units in a Folder in Index. This code OVERWRITES all existing custom metadata on a data unit.

Using `bundle` allows you to update up to 1000 label rows at a time.

<CodeGroup>
  ```python theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.http.bundle import Bundle
  from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

  # Authentication
  SSH_PATH = "<ssh-private-key>"
  FOLDER_HASH = "<unique-folder-id>"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  folder = user_client.get_storage_folder(FOLDER_HASH)
  items = folder.list_items()

  # Use the Bundle context manager
  with Bundle() as bundle:
      for item in items:
          # Update each item with client metadata
          item.update(client_metadata={"metadata-1": "value", "metadata-2": False}, bundle=bundle)
  ```
</CodeGroup>

#### Bulk custom metadata import on specific data units

This code allows you to update custom metadata on specific data units in a Folder in Index. This code DOES NOT OVERWRITE existing custom metadata on a data unit. It does overwrite custom metadata with existing values and adds new custom metadata to the data unit.

Using `bundle` allows you to update up to 1000 label rows at a time.

```python theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.http.bundle import Bundle
from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

# Authentication
SSH_PATH = "<ssh-private-key>"
FOLDER_HASH = "<unique-folder-id>"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
)

folder = user_client.get_storage_folder(FOLDER_HASH)
updates = {
    # "<data-unit-id>": {"metadata-1": "metadata-value"},
    # "<data-unit-id>": {"metadata-2": False},
    # "<data-unit-id>": {"metadata-1": "metadata-value"},
    # "<data-unit-id>": {"metadata-2": True}
}

# Use the Bundle context manager
with Bundle() as bundle:
    for storage_item in folder.list_items():
        # Update each item with client metadata
        update = updates[storage_item.uuid]
        storage_item.update(client_metadata=update, bundle=bundle)
```

#### Add custom metadata to images in an image group

The following script adds `clientMetadata` to all images / frames in a specified Image Group.

Ensure that you:

* Replace `<private_key_path>` with the file path to your private access key.
* Replace `<image-group-id>` with the File ID (UUID) of the target Image Group.
* Customize the `_get_metadata_for_image` function with the clientMetadata you want to add. To add unique metadata for each image, make the function dynamic by passing additional variables.

```python theme={"dark"}
from uuid import UUID
from encord import EncordUserClient
from encord.http.bundle import Bundle

# Initialize the SDK client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# Replace image-group-id with the File ID of the image group
image_group_uuid = "<image-group-id>"

# Function to define metadata for each image. Can be made dynamic by passing variables.
def _get_metadata_for_image(image):
    return {
        "field": "string",
        "another_field": "number",
    }

# Fetch the uploaded image group
uploaded_image_group = user_client.get_storage_item(image_group_uuid)

# Retrieve and update metadata for each image in the group
frame_items = uploaded_image_group.get_child_items()

with Bundle() as bundle:
    for frame_item in frame_items:
        # Update client metadata for each image
        frame_item.update(client_metadata=_get_metadata_for_image(frame_item), bundle=bundle)
        print (frame_item.client_metadata)

# Re-fetch and verify updates
updated_frame_items = uploaded_image_group.get_child_items()

for updated_frame_item in updated_frame_items:
    expected_metadata = _get_metadata_for_image(updated_frame_item)
    assert updated_frame_item.client_metadata == expected_metadata

print("Client metadata successfully added and verified for all images in the Image Group.")
```

***

## Datasets and custom metadata

<Info>
  Before importing custom metadata to Encord, [first import a metadata schema](#import-metadata-schema).

  We strongly recommend that you upload your custom metadata to Folders, instead of importing using Datasets. Importing custom metadata to data in Folders allows you to filter your data in Index by custom metadata.
</Info>

### List custom metadata (Datasets)

The following code lists the custom metadata of all data units in the specified Dataset. The code prints the custom metadata along with the data unit's index within the dataset.

```python theme={"dark"}

# Import dependencies
from encord import EncordUserClient
from encord.client import DatasetAccessSettings

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

# Specify a dataset to read or write metadata to
dataset = client.get_dataset("<dataset_hash>")

# Fetch the dataset's metadata
dataset.set_access_settings(DatasetAccessSettings(fetch_client_metadata=True))

# Read the metadata of all data units in the dataset.
for data_unit, data_row in enumerate(dataset.data_rows):
    print(f"{data_row.client_metadata} - Data Unit: {data_unit}")

```

### Deprecated - Import custom metadata (Datasets)

<Info>
  Importing custom metadata (`clientMetadata`) to data units in the Datasets is deprecated.
  [Import custom metadata to data units in Folders](#import-custom-metadata-folders) instead.
</Info>

<Info>
  Before importing custom metadata to Encord, [first import a metadata schema](#import-metadata-schema).
  We strongly recommend that you import your custom metadata to Folders, instead of importing to Datasets. Importing custom metadata to data in folders allows you to filter your data in Index by custom metadata.
</Info>

#### Import custom metadata to a specific data unit in your Dataset

You can import custom metadata (`clientMetadata`) to specific data units in the Dataset.

* Replace `<private_key_path>` with the path to your private key.
* Replace `<dataset_hash>` with the hash of your Dataset.
* Replace `Image1.png` and the other file names in the `metadata` variable with the names of the files in your Dataset to which you want to add metadata.

<Tip>
  You can find the \<data unit number> by [reading all metadata in the Dataset](#list-custom-metadata).
</Tip>

```python Multiple data units theme={"dark"}
from encord import EncordUserClient
from encord.client import DatasetAccessSettings

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
            )


# Specify a Dataset to read or write metadata to
dataset = user_client.get_dataset("<dataset_hash>")

# Fetch the dataset's metadata
dataset.set_access_settings(DatasetAccessSettings(fetch_client_metadata=True))

metadata = {
  'Image1.png': {"group-id": "A", 'layout-group': 'A'},
  'Image2.png': {"group-id": "B", 'layout-group': 'A'},
  'Image3.png': {"group-id": "C", 'layout-group': 'B'},
  'Image4.png': {"group-id": "D", 'layout-group': 'B'},
}

for data_row in dataset.data_rows:
  data_row.client_metadata = metadata[data_row['data_title']]
  data_row.save()
  print(data_row.client_metadata)

```

#### Import custom metadata (`clientMetadata`) to all data units in a Dataset

The following code adds the same custom metadata (`clientMetadata`) to each data unit in the specified dataset. The code prints the custom metadata along with the data units index within the dataset, so that you can verify that the custom metadata was set correctly.

```python theme={"dark"}

# Import dependencies
from encord import EncordUserClient
from encord.client import DatasetAccessSettings

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

# Specify a dataset to read or write metadata to
dataset = client.get_dataset("<dataset_hash>")

# Fetch the Dataset's metadata
dataset.set_access_settings(DatasetAccessSettings(fetch_client_metadata=True))

# Add metadata to all data units in the Dataset.
# Replace {"my": "metadata"} with the metadata you want to add
for data_unit, data_row in enumerate(dataset.data_rows):
    data_row.client_metadata = {"my": "metadata"}
    data_row.save()
    print(f"{data_row.client_metadata} - Data Unit: {data_unit}")

```

***

## Deprecated - Reserved Keywords

Reserved keywords are strings that are set aside for exclusive use. The following keywords are reserved:

* `keyframes`

### KEYFRAMES

`keyframes` is reserved for use with frames of interest in videos. Specifying `keyframes` on specific frames ensures that those frames import into Index and Active. That means frames specified using `keyframes` are available to filter your frames and for calculating embeddings on your data.

<CodeGroup>
  ```python keyframes Format theme={"dark"}

   client_metadata = {
       "keyframes": [<frame_number>, <frame_number>, <frame_number>, <frame_number>, <frame_number>]
  }
  ```

  ```python Example theme={"dark"}
  client_metadata = {
      "keyframes": [13, 17, 19, 23, 127, 149, 307, 557]
  }
  ```
</CodeGroup>

You can include `keyframes` while importing your videos or after you import your videos.

**Import `keyframes` to Specific Data Units (Folder)**:

This code allows you to import `keyframes` on specific videos in Index. This code DOES NOT OVERWRITE all existing custom metadata on a data unit. It does overwrite custom metadata with existing values and adds new custom metadata to the data unit.

<CodeGroup>
  ```python Boilerplate theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  # Authentication
  SSH_PATH = "<private_key_path>"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  # Define a dictionary with item UUIDs and their keyframes updates
  updates = {
      "<data-unit-id>": {"keyframes": [<frame_number>, <frame_number>, <frame_number>, <frame_number>, <frame_number>]},
      "<data-unit-id>": {"keyframes": [<frame_number>, <frame_number>, <frame_number>, <frame_number>, <frame_number>]},
      "<data-unit-id>": {"keyframes": [<frame_number>, <frame_number>, <frame_number>, <frame_number>, <frame_number>]},
      "<data-unit-id>": {"keyframes": [<frame_number>, <frame_number>, <frame_number>, <frame_number>, <frame_number>]}
  }

  # Update the storage items based on the dictionary
  for item_uuid, metadata_update in updates.items():
      item = user_client.get_storage_item(item_uuid=item_uuid)

      # make a copy of the current metadata and update it with the new metadata
      curr_metadata = item.client_metadata.copy()
      curr_metadata.update(metadata_update)

      # update the item with the new metadata
      item.update(client_metadata=curr_metadata)
  ```

  ```python Example 1 theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  # Authentication
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
  )

  # Define a dictionary with item UUIDs and their keyframes updates
  updates = {
      "8ad58157-ca74-4ae4-8f37-a0193430bcac": {"keyframes": [13, 17, 19, 23, 127, 149, 307, 557]},
      "f165fe81-1956-4347-81ca-3a3b198f3f23": {"keyframes": [10, 110, 210, 320, 430]},
      "9bd58157-ca74-4ae4-8f37-a0193431bcba": {"keyframes": [1087, 1549, 2029, 3527]},
      "62daaa33-195e-4faf-be5b-8335a239beb6": {"keyframes": [1000, 2001, 3241, 4637, 5431]}
  }

  # Update the storage items based on the dictionary
  for item_uuid, metadata_update in updates.items():
      item = user_client.get_storage_item(item_uuid=item_uuid)

      # make a copy of the current metadata and update it with the new metadata
      curr_metadata = item.client_metadata.copy()
      curr_metadata.update(metadata_update)

      # update the item with the new metadata
      item.update(client_metadata=curr_metadata)
  ```
</CodeGroup>


# Metadata Schema
Source: https://docs.encord.com/sdk-documentation/index-sdk/custom-metadata/sdk-index-metadata-schema



Before importing your custom metadata, we recommend importing a metadata schema. Schemas help Encord validate your custom metadata and instruct Index and Active how to display it.

<Tip>To manage custom metadata across multiple teams, we recommend using namespaced keys in your schema. This helps avoid conflicts—for example, one team might use `video.description`, while another uses `audio.description` or `TeamName.MetadataKey`. It keeps things organized and clear across departments.</Tip>

### Benefits of Using a Metadata Schema

Using a metadata schema provides several benefits:

* **Validation**: Ensures that all custom metadata conforms to predefined data types, reducing errors during data registration and processing.
* **Consistency**: Maintains uniformity in data types across different datasets and projects, which simplifies data management and analysis.
* **Filtering and Sorting**: Enhances the ability to filter and sort data efficiently in the Encord platform, enabling more accurate and quick data retrieval.

***

### Metadata Schema Table

<Tip>
  * Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and blank spaces ( ), hyphens (-), underscores (\_), and periods (.). Metadata schema keys are case sensitive.

  * If you are unsure about the type to assign to a metadata key, we recommend using `varchar` as a versatile default.
</Tip>

Use [.add\_scalar()](/sdk-documentation/sdk-references/client_metadata_schema#add-scalar) to add a scalar key to your metadata schema.

| Scalar Key | Description                                                                                                                                                                                | Display Benefits                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| boolean    | Binary data type with values "true" or "false".                                                                                                                                            | Filtering by binary values                        |
| datetime   | ISO 8601 formatted date and time.                                                                                                                                                          | Filtering by time and date                        |
| number     | Numeric data type supporting float values.                                                                                                                                                 | Filtering by numeric values                       |
| uuid       | UUIDv4 formatted unique identifier for a data unit.                                                                                                                                        | Filtering by customer specified unique identifier |
| varchar    | Textual data type. Formally `string`. `string` can be used as an alias for `varchar`, but we STRONGLY RECOMMEND that you use `varchar`.                                                    | Filtering by string.                              |
| text       | Text data with unlimited length (example: transcripts for audio). Formally `long_string`. `long_string` can be used as an alias for `text`, but we STRONGLY RECOMMEND that you use `text`. | Storing and filtering large amounts of text.      |

Use `add_enum` and `add_enum_options` to add an enum and enum options to your metadata schema.

| Key  | Description                                    | Display Benefits                                      |
| ---- | ---------------------------------------------- | ----------------------------------------------------- |
| enum | Enumerated type with predefined set of values. | Facilitates categorical filtering and data validation |

Use `add_embedding` to add an embedding to your metadata schema.

| Key       | Description                                | Display Benefits                                                                        |
| --------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
| embedding | 1 to 4096 for Index. 1 to 2000 for Active. | Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon) |

Use `add_geospatial` to add a new geospatial type to the metadata schema.

| Key        | Description                                                                                                                                                                        | Display Benefits                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| geospatial | Geospatial data that contains latitude and longitude information. Latitude values are between +90 (North) to -90 (South). Longitude values are between +180 (West) to -180 (East). | Filtering data by using a geospatial map. |

<Note>
  * Geospatial custom metadata is supported only in Index.

  * Geospatial custom metadata can be applied to all data unit types and on individual frames in videos.
</Note>

<Warning>
  Incorrectly specifying a data type in the schema can cause errors when filtering in Index or Active. To fix this, check your schema, correct any issues, re-import it, and re-sync your Active project.
</Warning>

<AccordionGroup>
  <Accordion title=" Deprecated ">
    While still supported, we STRONGLY RECOMMEND that you use the latest metadata schema instructions.

    | ENUM Name    | String Representation | Description                                                      | Display Benefits                                                                        |
    | ------------ | --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
    | NUMBER       | number                | Numeric data type supporting float values                        | Filtering by numeric values                                                             |
    | STRING       | string                | Textual data type                                                | Filtering by string                                                                     |
    | BOOLEAN      | boolean               | Binary data type with values "true" or "false"                   | Filtering by binary values                                                              |
    | DATETIME     | datetime              | ISO 8601 formatted date and time                                 | Filtering by time and date                                                              |
    | ENUM         | enum                  | Enumerated type with predefined set of values                    | Facilitates categorical filtering and data validation                                   |
    | EMBEDDING    | embedding             | 1 to 4096 for Index. 1 to 2000 for Active.                       | Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon) |
    | LONG\_STRING | long\_string          | Text data with unlimited length (example: transcripts for audio) | Storing and filtering large amounts of text                                             |

    <Warning>
      Incorrectly specifying a data type in the schema can cause errors when filtering your data in Index or Active. If you encounter errors while filtering, [verify your schema](/platform-documentation/Curate/custom-metadata/index-metadata-schema#verify-your-schema) is correct. If your schema has errors, correct the errors, re-import the schema, and then re-sync your Active Project.
    </Warning>
  </Accordion>
</AccordionGroup>

***

### Import Your Metadata Schema to Encord

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("metadata_1", data_type="boolean")
  metadata_schema.add_scalar("metadata_2", data_type="datetime")
  metadata_schema.add_scalar("metadata_3", data_type="number")
  metadata_schema.add_scalar("metadata_4", data_type="uuid")
  metadata_schema.add_scalar("metadata_5", data_type="varchar")
  metadata_schema.add_scalar("metadata_6", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("my-enum", values=["enum-value-01", "enum-value-02", "enum-value-03"])

  # Add embedding fields
  metadata_schema.add_embedding('my-test-active-embedding', size=512)
  metadata_schema.add_embedding('my-test-index-embedding', size=<values-from-1-to-4096>)

  # Add geospatial
  metadata_schema.add_geospatial('geo-point')

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Add various metadata fields
  metadata_schema.add_scalar("G2G", data_type="boolean")
  metadata_schema.add_scalar("Date", data_type="datetime")
  metadata_schema.add_scalar("Cost", data_type="number")
  metadata_schema.add_scalar("Priority", data_type="number")
  metadata_schema.add_scalar("ID-Sys-01", data_type="uuid")
  metadata_schema.add_scalar("ID-Sys-02", data_type="uuid")
  metadata_schema.add_scalar("Description", data_type="varchar")
  metadata_schema.add_scalar("Location", data_type="varchar")
  metadata_schema.add_scalar("Address", data_type="varchar")
  metadata_schema.add_scalar("Translation en-gb", data_type="text")
  metadata_schema.add_scalar("Translation en-ca", data_type="text")
  metadata_schema.add_scalar("Translation en-us", data_type="text")
  metadata_schema.add_scalar("Translation zh-tw", data_type="text")
  metadata_schema.add_scalar("Translation zh-hk", data_type="text")
  metadata_schema.add_scalar("Translation zh-cn", data_type="text")

  # Add an enum field
  metadata_schema.add_enum("ready", values=["ripe", "partially-ripe", "unripe"])
  metadata_schema.add_enum("Fruit", values=["Blueberries", "Cherries", "Apples", "Kiwi"])

  # Add embedding fields
  metadata_schema.add_embedding("active-embedding-01", size=512)
  metadata_schema.add_embedding("active-embedding-02", size=512)
  metadata_schema.add_embedding("index-embedding-100", size=100)
  metadata_schema.add_embedding("index-embedding-1000", size=1000)

  # Add geospatial
  metadata_schema.add_geospatial("Coordinates")

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

***

<AccordionGroup>
  <Accordion title=" Deprecated ">
    This is supported, as is, we STRONGLY RECOMMEND that you use the most current method of creating your custom metadata schema.

    <CodeGroup>
      ```python Import schema template theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

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

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH
      )

      user_client.set_client_metadata_schema_from_dict({'metadata_1': 'data type', 'metadata_2': 'data type', 'metadata_3': 'data type'})

      ```

      ```python Example theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

      SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH
      )

      user_client.set_client_metadata_schema_from_dict({'captured_at': 'datetime', 'city': 'datetime', 'dark': 'boolean'})

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

### Verify Your Schema

After importing your schema to Encord we recommend that you verify that the import is successful. Run the following code to verify your metadata schema imported and that the schema is correct.

<CodeGroup>
  ```python Verify schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Verify your schema example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()

  # Print the schema for verification
  print(metadata_schema)
  ```
</CodeGroup>

***

<AccordionGroup>
  <Accordion title=" Deprecated ">
    This is supported, as is, we STRONGLY RECOMMEND that you use the most current method of creating your custom metadata schema.

    <CodeGroup>
      ```python Verify your schema template theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

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

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH
      )

      schema = user_client.get_client_metadata_schema()

      print(schema)

      ```

      ```python Verify your schema example theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient

      SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH
      )

      schema = user_client.get_client_metadata_schema()

      print(schema)

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## Edit Schema Keys

You can change the data type of schema keys using the [`.set_scalar()`](/sdk-documentation/sdk-references/client_metadata_schema#delete-key) method. The example below shows how to update the data type for multiple metadata fields.

```python Restore Schema Key theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.metadata_schema import MetadataSchema

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get your metadata schema
metadata_schema = user_client.metadata_schema()

# Edit various metadata fields
metadata_schema.set_scalar("metadata_1", data_type="number")
metadata_schema.set_scalar("metadata_2", data_type="boolean")
metadata_schema.set_scalar("metadata_3", data_type="boolean")

# Print the schema for verification
print(metadata_schema)
```

***

## Delete Schema Keys

<Tip> Schema key options cannot be deleted. Instead, we recommend creating new schema key options to meet your needs and phasing out any that are no longer required.</Tip>

You can delete schema keys using the [.delete() method](/sdk-documentation/sdk-references/client_metadata_schema#delete-key).

There are two types of deletion: **hard delete** and **soft delete**. A hard delete permanently removes the key, making it impossible to restore. A soft delete allows you to restore the key later using the [.restore\_key()](/sdk-documentation/sdk-references/client_metadata_schema#restore-key) method.

The following examples show hard delete and soft deletion of a schema key called `Fruit`.

<CodeGroup>
  ```python Soft Delete theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Get your metadata schema
  metadata_schema = user_client.metadata_schema()

  metadata_schema.delete_key(k: "Fruit", hard: False)

  # Print the schema for verification
  print(metadata_schema)
  ```

  ```python Hard Delete theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Get your metadata schema
  metadata_schema = user_client.metadata_schema()

  metadata_schema.delete_key(k: "Fruit", hard: True)

  # Print the schema for verification
  print(metadata_schema)
  ```
</CodeGroup>

### Restore Schema Keys

Keys that have been soft deleted can be restored using the [.restore\_key()](/sdk-documentation/sdk-references/client_metadata_schema#restore-key) method. The following example restores a schema key called `Fruit`.

```python Restore Schema Key theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.metadata_schema import MetadataSchema

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get your metadata schema
metadata_schema = user_client.metadata_schema()

metadata_schema.restore_key(k: "Fruit")

# Print the schema for verification
print(metadata_schema)
```


# Add Files to Datasets
Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-add-files-to-datasets



<Note>When using the legacy method [add\_private\_data\_to\_dataset\_start](/sdk-documentation/sdk-references/dataset#add-private-data-to-dataset-start) to upload files directly to a Dataset must specify a StorageFolder object or a folder uuid.</Note>

Once your data is uploaded in **Data** > **Files & Folders** it can be attached to multiple Datasets. The following scripts add all files in a specified folder to a Dataset.

* Replace `<private_key_path>` with the path to your private key.
* Replace `<folder_name>` with the name you want to give your Storage folder.
* Replace `<dataset_hash>` with the hash of the Dataset you want to add the data units to.

<Note>Files added to the folder at a later time **will not** be automatically added to the Dataset.</Note>

```python All files theme={"dark"}
from encord import EncordUserClient

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1))

dataset = user_client.get_dataset("<dataset_hash>")

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List all data units
    items = list(storage_folder.list_items())

    # Collect all item UUIDs
    item_uuids = [item.uuid for item in items]

    # Output the retrieved data units
    for item in items:
        print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")

    # Link all items at once if there are any
    if item_uuids:
        dataset.link_items(item_uuids)
else:
    print("Folder not found.")
```


# Collections for Data Curation
Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-collections

Learn the basics of using the Collections for Data Curation with the Encord SDK.

Collections are saved groups of data units or labels that let you curate subsets of your data and perform bulk actions on them, such as sending items to annotation, running bulk classifications, or exporting a curated Dataset.

## Filter Presets

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

### Create Filter Preset

Create a Filter Preset based on raw JSON.

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

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


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

  # Create a preset

  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 ...
                  }
              ]
          }
      },
  )

  print(preset)

  ```

  ```python Example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"


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

  # Create a preset

  preset = user_client.create_preset(
      name="Vehicle Speed",
      description="Specifies the speed of cars, trucks, and motorcycles.",
      filter_preset_json={
          "global_filters": {
              "filters": [
                  {
                      "key": "speed",
                      "type": "client_meta_number",
                      "values": [50, 100],
                      "include": True,
                  }
              ]
          }
      },
  )

  print(preset)

  ```
</CodeGroup>

### Update Filter Presets

<Note>All arguments are optional when updating a filter preset.</Note>

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

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

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


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

  # Update a preset

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

  print(preset)

  ```

  ```python Example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

  # Preset ID to add to the collection
  PRESET_ID = "unique-preset-filter-id" 

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

  # Update a preset

  preset = user_client.get_filter_preset(preset_uuid=PRESET_ID)
  preset.update_preset(
      filter_preset_json={
          "global_filters": {
              "filters": [
                  {
                      "key": "speed (kph)",
                      "type": "client_meta_number",
                      "values": [70, 120],
                      "include": True,
                  }
              ]
          }
      },
  )

  print(preset)

  ```
</CodeGroup>

### Delete Filter Presets

```python Delete Preset template theme={"dark"}

# Import dependencies
from encord import EncordUserClient

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

# Preset ID to add to the collection
PRESET_ID = "unique-preset-filter-id"  

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

# Delete the preset by ID
user_client.delete_preset(PRESET_ID)

```

### List Filter Presets

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

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

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


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

  # Get Preset Filters
  presets = user_client.list_presets()

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

  ```

  ```python Example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"


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

  # Get Preset Filters
  presets = user_client.list_presets()

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

  ```
</CodeGroup>

### List Filters in Filter Preset

This code lists the filters that make up the filter preset into a JSON file format.

Filters are of the following types:

* Global filters: Global filters can apply to the data in any top-level Folder. Examples: Data type, Storage Location, Quality Metrics.

* Local filters: Local filters can apply ONLY to specific top-level Folders. Examples: Data title, File ID, Collection.

Returned results are a combination of Global and Local filters. While Global filters provide information about filter, Local filters provide a raw filter ID.

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

  from pprint import pprint

  from encord.orm.filter_preset import FilterPreset as OrmFilterPreset

  SSH_PATH = "/file/path/to/your/ssh-private-key.txt"
  PRESET_ID = "00000000-0000-0000-0000-000000000000"

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

  filters = user_client.get_filter_preset(preset_uuid=PRESET_ID).get_filter_preset_json()

  filters_dict = filters.to_dict() 

  print("\nFormatted Output:\n")
  pprint(filters_dict)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient

  from pprint import pprint

  from encord.orm.filter_preset import FilterPreset as OrmFilterPreset

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

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

  filters = user_client.get_filter_preset(preset_uuid=PRESET_ID).get_filter_preset_json()

  filters_dict = filters.to_dict() 

  print("\nFormatted Output:\n")
  pprint(filters_dict)

  ```

  ```json Output from Example theme={"dark"}

  Formatted Output:

  {'globalFilters': {'filters': [{'domain': 'item',
                                  'enum': 'data_type',
                                  'include': True,
                                  'type': 'enum',
                                  'values': ['IMAGE']}]},
   'localFilters': {'raw-filter-id': {'filters': []}}}

  ```
</CodeGroup>

### Add Filter Preset Contents to Collection

Adds all storage items that match the criteria specified by a filter preset to a Collection.

<CodeGroup>
  ```python Template theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "file-path-to-ssh-private-key"
  COLLECTION_HASH = "unique-collection-id"

  # Preset ID to add to the collection
  PRESET_ID = "unique-preset-filter-id"  

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  # Add preset storage items to the collection by preset ID
  collection.add_preset_items(PRESET_ID)

  print(f"Added preset {PRESET_ID} to collection {COLLECTION_HASH}.")

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  COLLECTION_HASH = "9a423f8f-0d3d-48ee-9fd6-0b2b80d229e7"

  # Preset Filter ID to add to the collection
  PRESET_ID = "2eb7c0e2-bc4f-4583-991c-2acb7dec4a72"  

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  # Add preset storage items to the collection by preset ID
  collection.add_preset_items(PRESET_ID)

  print(f"Added preset {PRESET_ID} to collection {COLLECTION_HASH}.")

  ```
</CodeGroup>

### Remove Filter Preset Contents from Collection

Removes all storage items that match the criteria specified by a filter preset from a Collection.

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "file-path-to-key-private-key"
  COLLECTION_HASH = "collection-unique-id"

  # Preset ID to remove contents from the collection
  PRESET_ID = "preset-filter-unique-id"  

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  # Remove preset storage items from the collection by preset ID
  collection.remove_preset_items(PRESET_ID)

  print(f"Removed preset {PRESET_ID} from collection {COLLECTION_HASH}.")
  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "/Users/chirs-encord/sdk-ssh-private-key.txt"
  COLLECTION_HASH = "078c1568-d46b-4f64-adf5-e16e8473f25d"

  # Preset ID to remove contents from the collection
  PRESET_ID = "e57cbab1-3be4-4485-bdfe-5747796b7800"  

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  # Remove preset storage items from the collection by preset ID
  collection.remove_preset_items(PRESET_ID)

  print(f"Removed preset {PRESET_ID} from collection {COLLECTION_HASH}.")
  ```
</CodeGroup>

## Collections

Collections are groups of data units you selected by filtering, sorting, inspecting, and analyzing the data units in Index.

### List Collections

List all Collections in Index by name with their unique identifier.

<CodeGroup>
  ```python Template theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  SSH_PATH = "file-path-to-your-ssh-private-key"


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

  # Get Collection

  collections = user_client.list_collections()

  # Print out the names of the Collections
  for collection in collections:
      print(collection.name, collection.uuid)

  ```

  ```python Example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"


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

  # Get Collection

  collections = user_client.list_collections()

  # Print out the names of the Collections
  for collection in collections:
      print(collection.name, collection.uuid)
  ```
</CodeGroup>

### Create Collection

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

<CodeGroup>
  ```python Template theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

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


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

  # Create a 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.")

  print(collection)
  ```

  ```python Example theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"


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

  # Create a Collection

  collection = user_client.create_collection(top_level_folder_uuid="cdb9eacd-46a6-4982-8d0e-4cafbf248a38", name="SDK-Collection-01", description="A Collection created using the SDK.")

  print(collection)
  ```
</CodeGroup>

### Add Storage Items to a Collection using UUIDs

Add storage items to a Collection using the UUID of the storage items.

<CodeGroup>
  ```python Template theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "file-path-to-ssh-private-key"
  COLLECTION_HASH = "collection-unique-id"

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  updates = [
      "<storage-item-id-01>",
      "<storage-item-id-02>",
      "<storage-item-id-03>"
  ]


  collection.add_items(updates)

  print(f"Added storage items {updates} to collection {COLLECTION_HASH}.")

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  COLLECTION_HASH = "9a423f8f-0d3d-48ee-9fd6-0b2b80d229e7"

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  updates = [
      "fd332087-3691-48b9-bb46-19c4cdcd6099",
      "62daaa33-195e-4faf-be5b-8335a239beb6",
      "c1dac9ff-cd92-4029-b178-e093f8a803af"
  ]


  collection.add_items(updates)

  print(f"Added storage items {updates} to collection {COLLECTION_HASH}.")
  ```
</CodeGroup>

### Remove Storage Items from a Collection using UUIDs

Remove storage items from a Collection using UUIDs.

<CodeGroup>
  ```python Template theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "file-path-to-ssh-private-key"
  COLLECTION_HASH = "collection-unique-id"

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  updates = [
      "<storage-item-id-01>",
      "<storage-item-id-02>",
      "<storage-item-id-03>"
  ]


  collection.remove_items(updates)

  print(f"Removed storage items {updates} from collection {COLLECTION_HASH}.")

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  COLLECTION_HASH = "9a423f8f-0d3d-48ee-9fd6-0b2b80d229e7"

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  updates = [
      "fd332087-3691-48b9-bb46-19c4cdcd6099",
      "62daaa33-195e-4faf-be5b-8335a239beb6",
      "c1dac9ff-cd92-4029-b178-e093f8a803af"
  ]


  collection.remove_items(updates)

  print(f"Removed storage items {updates} from collection {COLLECTION_HASH}.")

  ```
</CodeGroup>

### List all Storage Items in a Collection

Lists all storage items in a Collection

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.storage import StorageItemType
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "file-path-to-ssh-private-key"
  COLLECTION_HASH = "collection-unique-id"

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  # Initialize an empty list to store items
  items = []

  # Iterate over storage items and append them to the list
  for item in collection.list_items():
      items.append(item)
      print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.storage import StorageItemType
  from encord.orm.collection import Collection
  from encord.orm.filter_preset import FilterPreset

  # Define constants
  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  COLLECTION_HASH = "078c1568-d46b-4f64-adf5-e16e8473f25d"

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

  # Fetch the specific collection by hash
  collection: Collection = user_client.get_collection(COLLECTION_HASH)

  # Initialize an empty list to store items
  items = []

  # Iterate over storage items and append them to the list
  for item in collection.list_items():
      items.append(item)
      print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")

  ```
</CodeGroup>


# Custom Embeddings
Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-custom-embeddings

Learn how to import custom embeddings using the Encord SDK.

Encord enables the use of custom embeddings for images, image sequences, image groups, and individual video frames. Custom embeddings allow you to incorporate your own feature representations into Encord's platform, enhancing capabilities like similarity search, visualizations, and data filtering. This flexibility supports more advanced workflows and deeper insights tailored to your specific use cases.

<Info>Support for videos (in their entirety) is coming soon.</Info>

## Custom Embeddings Support

We currently support embeddings of dimensions ranging from 1 to 4096 for Index, and 1 to 2000 for Active, following on from our in-house clip Embeddings.

## Import Custom Embeddings

To bring your custom embeddings into Encord, you first need to create a key in your metadata schema. After the key is in your schema, you can import your custom embeddings.

### Step 1: Create a New Embedding Type

A key is required in your custom metadata schema for your embeddings. You can use any string as the key for your embeddings. We strongly recommend that you use a string that is meaningful.

If you do not include a key in your metadata schema, your imported embeddings are treated as strings.

<Tip>Embedding key names can contain alphanumeric (a-z, A-Z, 0-1) characters, hyphens, and underscores.</Tip>

Use `add_embedding` to add an embedding to your metadata schema.

<Info>
  We currently support embeddings of:

  * 1 to 4,096 dimensions for data curation.
  * 1 to 2,000 dimensions for label validation.
</Info>

<CodeGroup>
  ```python Import schema template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

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

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()


  # Add embedding fields
  metadata_schema.add_embedding('my-test-active-embedding', size=512)
  metadata_schema.add_embedding('my-test-index-embedding', size=<values-from-1-to-4096>)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  from encord.metadata_schema import MetadataSchema

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

  # Authenticate with Encord using the path to your private key
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Create the schema
  metadata_schema = user_client.metadata_schema()


  # Add embedding fields
  metadata_schema.add_embedding('active-embedding-01', size=512)
  metadata_schema.add_embedding('active-embedding-02', size=512)
  metadata_schema.add_embedding('index-embedding-100', size=100)
  metadata_schema.add_embedding('index-embedding-1000', size=1000)

  # Save the schema
  metadata_schema.save()

  # Print the schema for verification
  print(metadata_schema)

  ```
</CodeGroup>

### Step 2: Upload Embeddings

With the key in the custom metadata schema ready, we can now import our embeddings.

Custom embedding sizes are flexible and can be set anywhere between 1 and 4096.

You can import embeddings after you have added your data or during your data registration.

<Note>Your key frames (frames specified with or without embeddings) always appear in Encord, regardless of what sampling rate you specify.</Note>

<Tip>Embedding key names can contain alphanumeric (a-z, A-Z, 0-1) characters, hyphens, and underscores.</Tip>

If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

<Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video.</Info>

<AccordionGroup>
  <Accordion title="Import while registering videos">
    #### Import while importing videos

    This JSON file imports embeddings while registering your data with Encord from a cloud integration.

    `config` is optional when importing your custom embeddings:

    ```json theme={"dark"}
    "config": {
        "sampling_rate": "<samples-per-second>",
        "keyframe_mode": "frame" or "seconds",
    },
    ```

    If `config` is not specified, the `sampling_rate` is 1 frame per second, and the `keyframe_mode` is `frame`.

    <Info>Specifying a `sampling_rate` of `0` only imports the first frame and all keyframes of your video.</Info>

    <CodeGroup>
      ```json Import Embeddings Template theme={"dark"}

      {
          "videos": [
              {
                  "objectUrl": "<cloud-file-path-to-your-video-1>",
                  "title": "<title-for-your-video-1>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<samples-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "<cloud-file-path-to-your-video-2>",
                  "title": "<title-for-your-vide-2>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<frames-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "<cloud-path-to-your-video-3>",
                  "title": "<title-for-your-video-3>",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "<frames-per-second>",
                              "keyframe_mode": "frame" or "seconds",
                          },
                          "frames": {
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              },
                              "<frame-number-or-seconds>": {
                                  "<my-embedding>": [1.0, 2.0, 3.0]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```

      ```json Example - Simple theme={"dark"}
      {
          "videos": [
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-001.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "111": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "113": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-002.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "157": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "257": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-003.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "frames": {
                              "11": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "13": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```

      ```json Example - Advanced theme={"dark"}
      {
          "videos": [
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-001.mp4",
                  "title": "awesome-video-001.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "0",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "111": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "113": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-002.mp4",
                  "title": "awesome-video-002.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "3",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "157": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "257": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              },
              {
                  "objectUrl": "https://storage.cloud.google.com/my-cloud-bucket/awesome-video-003.mp4",
                  "title": "awesome-video-003.mp4",
                  "clientMetadata": {
                      "$encord": {
                          "config": {
                              "sampling_rate": "4",
                              "keyframe_mode": "frame"
                          },
                          "frames": {
                              "11": {
                                  "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                              },
                              "13": {
                                  "embeddings-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656]
                              }
                          }
                      }
                  }
              }
          ],
          "skip_duplicate_urls": true
      }

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update specific videos">
    #### Update specific videos

    <CodeGroup>
      ```python Boilerplate theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

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

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "<data-hash-1>": {
              "$encord": {
                  "frames": {
                      "<frame-number-1>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      },
                      "<frame-number-2>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "<data-hash-2>": {
              "$encord": {
                  "config": {
                      "sampling_rate": <samples-per-second>,  # VIDEO ONLY (optional default = 1 sample/second)
                      "keyframe_mode": "frame" or "seconds",  # VIDEO ONLY (optional default = "frame")
                  },
                  "frames": {
                      "<frame-number-1>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      },
                      "<frame-number-2>": {
                          "<my-embedding>": [1.0, 2.0, 3.0],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)
      ```

      ```python Example - Simple theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

      # Authentication
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "f2155fa4-6040-408a-84d5-72bacb4f45db": {
              "$encord": {
                  "frames": {
                      "113": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "131": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "f235ad84-f9eb-4dc1-934d-d05e1cd70e59": {
              "$encord": {
                  "frames": {
                      "171": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "231": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)

      ```

      ```python Example - Advanced theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.http.bundle import Bundle
      from encord.orm.storage import StorageFolder, StorageItem, StorageItemType, FoldersSortBy

      # Authentication
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      # Authenticate with Encord using the path to your private key
      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=SSH_PATH,
      )

      updates = {
          "6b8d797a-4655-43c3-b251-cbd6cc995bc6": {
              "$encord": {
                  "config": {
                      "sampling_rate": 0,  # VIDEO ONLY (optional default = 1 sample/second)
                  },
                  "frames": {
                      "111": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "222": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
          "d9185f6e-3dbc-443b-bd37-77b2f34f157e": {
              "$encord": {
                  "config": {
                      "sampling_rate": 2,  # VIDEO ONLY (optional default = 1 sample/second)
                      "keyframe_mode": "frame",  # VIDEO ONLY (optional default = "frame")
                  },
                  "frames": {
                      "333": {
                          "embedding-10": [0.9361826107513869, 0.44445671908774165, 0.3083308253882048, 0.017454463823556754, 0.7765154602640884, 0.39951939694747884, 0.14421315329564477, 0.8533255560056869, 0.3945949167412638, 0.34428458069417656],  # custom embedding ("embedding") with float values
                      },
                      "444": {
                          "embedding-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822],  # custom embedding ("embedding") with float values
                      }
                  }
              }
          },
      }

      # Use the Bundle context manager
      with Bundle() as bundle:
          # Update the storage items based on the dictionary
          for item_uuid, metadata_update in updates.items():
              item = user_client.get_storage_item(item_uuid=item_uuid)

              # Make a copy of the current metadata and update it with the new metadata
              curr_metadata = item.client_metadata.copy()
              curr_metadata.update(metadata_update)

              # Update the item with the new metadata and bundle
              item.update(client_metadata=curr_metadata, bundle=bundle)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Import while registering data units">
    #### Import while importing data units

    This JSON file imports embeddings while registering your data with Encord from a cloud integration.

    <CodeGroup>
      ```json Template theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "file/path/to/data-unit/file-name-01.file-extension",
            "title": "data-unit-title.file-extension",
            "clientMetadata": {"metadata-1": "value", "metadata-2": "value"}
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Example - Simple theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 01",
            "clientMetadata": {
              "embeddings-10": [0.44931257187793305, 0.11303790771089994, 0.9001464760810051, 0.2798273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-02.jpg",
            "title": "Blueberry 02",
            "clientMetadata": {
              "embeddings-10": [0.44531257187793305, 0.22303790771089994, 0.1101464760810051, 0.3898273275803421, 0.06879531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-01.jpg",
            "title": "Blueberry 03",
            "clientMetadata": {
              "embeddings-10": [0.45631257187793305, 0.23403790771089994, 0.1211464760810051, 0.3678273275803421, 0.06849531104035541, 0.8275038481160373, 0.9419277893526817, 0.7294979532997635, 0.18146276890284674, 0.07504156777630822]
                }
          },
        ],
        "skip_duplicate_urls": true
      }
      ```

      ```json Example - Advanced theme={"dark"}
      {
        "images": [
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-01.jpg",
            "title": "Cherry 01",
            "clientMetadata": {
              "Dark": false,
              "Location": "NY",
              "Date": "2024-06-13",
              "ACME Co ID": "8ada6567-c034-4bd4-91d0-04dab5d729d5",
              "Priority": "1",
              "embeddings-10": [
                0.67831257187793305,
                0.32603790771089994,
                0.4341464760810051,
                0.9748273275803421,
                0.23549531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-02.jpg",
            "title": "Cherry 02",
            "clientMetadata": {
              "Dark": false,
              "Location": "NY",
              "Date": "2024-06-13",
              "ACME Co ID": "1262bf57-402e-427c-8c60-276df65513ea",
              "Priority": "1",
              "embeddings-10": [
                0.42531257187793305,
                0.33403790771089994,
                0.5671464760810051,
                0.3688273275803421,
                0.06849531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          },
          {
            "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-03.jpg",
            "title": "Cherry 03",
            "clientMetadata": {
              "Dark": true,
              "Location": "OH",
              "Date": "2024-06-13",
              "ACME Co ID": "3000919f-01e2-4574-a4fd-a2790c4f7b8b",
              "Priority": "2",
              "embeddings-10": [
                0.22231257187793305,
                0.44503790771089994,
                0.7341464760810051,
                0.8368273275803421,
                0.06849531104035541,
                0.8275038481160373,
                0.9419277893526817,
                0.7294979532997635,
                0.18146276890284674,
                0.07504156777630822
              ]
            }
          }
        ],
        "skip_duplicate_urls": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Update specific data units">
    #### Import specific data units

    The custom embeddings format for images, text files, PDFs, and audio files follows the same format as [importing custom metadata](/platform-documentation/Curate/custom-metadata/import-custom-metadata#folders-and-custom-metadata).

    ```python theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient
    from encord.http.bundle import Bundle

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

    # Authenticate with Encord using the path to your private key
    user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=SSH_PATH,
    )

    # Define a dictionary with item UUIDs and their respective metadata updates
    updates = {
        "<data-ID-1>": {"<my-embedding>": [1.0, 2.0, 3.0]},
        "<data-ID-2>": {"<my-embedding>": [1.0, 2.0, 3.0]}
    }

    # Use the Bundle context manager
    with Bundle() as bundle:
        # Update the storage items based on the dictionary
        for item_uuid, metadata_update in updates.items():
            item = user_client.get_storage_item(item_uuid=item_uuid)

            # Make a copy of the current metadata and update it with the new metadata
            curr_metadata = item.client_metadata.copy()
            curr_metadata.update(metadata_update)

            # Update the item with the new metadata and bundle
            item.update(client_metadata=curr_metadata, bundle=bundle)

    ```
  </Accordion>
</AccordionGroup>

## Final Setup for Custom Embeddings

Once you import custom embeddings to your data (during cloud data registration or to existing data in Encord), there is a bit more setup required in Index and Active. These steps can only be performed from the UI.

<div lang="en">
  <head>
    <meta />

    <meta name="viewport" />

    <title>Clickable Div</title>
  </head>

  <div>
    <a href="/platform-documentation/Curate/custom-embeddings#3-select-your-custom-embeddings">
      Custom Embeddings for Curation
    </a>

    <a href="/platform-documentation/Validation/validation-custom-embeddings#3-select-your-custom-embeddings">
      Custom Embeddings for Label Validation
    </a>
  </div>
</div>

## Use Custom Embeddings

Custom embeddings in Index and Active allow you to:

* Perform similarity searches on your data with custom embeddings
* Adjust the similarity distance on similarity searches
* View your data in a 2D embedding plot graph
* Filter your data based on whether it has custom embeddings or not (Index only)


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

Learn how to use Data Groups in Encord using the SDK.

"Data Grouping" (Data Groups) allows you to allocate individual files to groups so that they are more easily annotated and reviewed. This allows you to unlock multi-tile and multi-modal functionality.

Basically, Data Groups are like image groups in Encord, except that Data Groups can include any data type (images, videos, audio files, text files, PDFs) AND that data groups support default and custom layouts for annotation and review.

<Note>
  You can use Data Groups in non-Consensus Projects and Consensus Projects with Review & Refine nodes. Determine Consensus nodes are not yet supported.
</Note>

<Tip>
  * For an end-to-end example of how you can use Data Groups, go [here](/end-to-end/Features/e2e-data-groups).

  * For instructions on exporting labels go [here](/sdk-documentation/sdk-labels/sdk-export#export-labels-as-json).
</Tip>

<Warning>
  **Deprecated (SDK v0.1.195):** Working on a Data Group's **child** label rows directly — by passing `include_children=True` to `list_label_rows_v2()`, or by reading `DataGroupMetadata.children` — is deprecated. Work on the Data Group **parent** instead, and access each child through its Label Space with [`LabelRowV2.get_spaces()`](/sdk-documentation/sdk-labels/sdk-data-group-labels#get-label-spaces). See [Data Groups & Label Spaces](/sdk-documentation/sdk-labels/sdk-data-group-labels) for the full workflow. The examples on this page use the parent-based approach.
</Warning>

## Create Data Groups

Each of the code examples does the following:

1. Specifies the data units to add to a Data Group.

2. Creates the Data Groups and specifies the layout in the Label Editor.

<Tip>
  Each example create multiple Data Groups. To create a single data group, replace `create_data_groups` with `create_data_group`.
</Tip>

3. Adds the Data Groups to a Dataset.

4. Adds the Dataset to a Project.

### Data Group - Grid (Default)

Grid Data Groups allow you to arrange multiple data units in a fixed, ordered grid within the Label Editor.

The order of the data units in the group determines their visual arrangement in the grid.

<Note>
  All layouts (grid, carousel, custom) are limited to 50 data units. Attempting to create a data group with more than 50 data units results in an error.
</Note>

**3 data unit Data Group Grid**

<img />

**12 data unit Data Group Grid**

<img />

**Requirements**

To display data units in a grid layout, you need:

* A list of data unit UUIDs in the exact order they should appear in the grid.

* A call to DataGroupGrid(...) when creating the Data Group:

**Example**

```python Data Group - Grid expandable theme={"dark"}

from uuid import UUID
from typing import List

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupGrid, StorageItemType
from encord.user_client import EncordUserClient

# --- 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)

created_group_uuids = folder.create_data_groups(
    [
        DataGroupGrid(
            name="group-grid-001",
            layout_contents=[
                UUID("00000000-0000-0000-0000-000000000000"),
                UUID("11111111-1111-1111-1111-111111111111"),
                UUID("22222222-2222-2222-2222-222222222222"),
                UUID("33333333-3333-3333-3333-333333333333"),
            ],
            client_metadata={"key": "value"},
        ),
        DataGroupGrid(
            name="group-grid-002",
            layout_contents=[
                UUID("44444444-4444-4444-4444-444444444444"),
                UUID("55555555-5555-5555-5555-555555555555"),
                UUID("66666666-6666-6666-6666-666666666666"),
                UUID("77777777-7777-7777-7777-777777777777"),
            ],
            client_metadata={"key": "value"},
        ),
        DataGroupGrid(
            name="group-grid-003",
            layout_contents=[
                UUID("88888888-8888-8888-8888-888888888888"),
                UUID("99999999-9999-9999-9999-999999999999"),
                UUID("12312312-3123-1231-2312-312312312312"),
                UUID("45645645-6456-4564-5645-645645645645"),
            ],
            client_metadata={"key": "value"},
        ),
    ]
)

print("✅ Created groups:", created_group_uuids)


# --- Add all the Data Groups in a folder to a Dataset ---
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# --- Retrieve and inspect Data Group label rows ---
p = user_client.get_project(PROJECT_ID)
rows = p.list_label_rows_v2()

# Inspect each Data Group's children through its Label Spaces
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        for space in row.get_spaces():
            print(
                f"space_id: {space.space_id}, "
                f"file_name: {space.metadata.file_name}, "
                f"layout_key: {space.metadata.layout_key}"
            )
```

### Data Group - Carousel/List

The order of data units in a Data Group determines how they are arranged in the Label Editor.

In the carousel/list layout, a scrollable panel on the left shows all data units in the Data Group, while the currently selected data unit appears in the main editor view.

<img />

**Requirements**

To display data units in a grid layout, you need:

* A list of data unit UUIDs in the exact order they should appear in the grid.

* A call to `DataGroupCarousel(...)` when creating the data group:

**Example**

```python Data Group - Carousel expandable theme={"dark"}

from uuid import UUID
from typing import List

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupCarousel, StorageItemType
from encord.user_client import EncordUserClient

# --- 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)

created_group_uuids = folder.create_data_groups(
    [
        DataGroupCarousel(
            name="group-carousel-001",
            layout_contents=[
                UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID 
                UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID 
                UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID 
                UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID 
            ],
            client_metadata={"key": "value"},
        ),
        DataGroupCarousel(
            name="group-carousel-002",
            layout_contents=[
                UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID 
                UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID 
                UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID 
                UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID 
            ],
            client_metadata={"key": "value"},
        ),
        DataGroupCarousel(
            name="group-carousel-003",
            layout_contents=[
                UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID 
                UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID 
                UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID 
                UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID 
            ],
            client_metadata={"key": "value"},
        ),
    ]
)

print("✅ Created carousel groups:", created_group_uuids)

# --- Add all the Data Groups in a folder to a Dataset ---
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# --- Retrieve and inspect Data Group label rows ---
p = user_client.get_project(PROJECT_ID)
rows = p.list_label_rows_v2()

# Inspect each Data Group's children through its Label Spaces
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        for space in row.get_spaces():
            print(
                f"space_id: {space.space_id}, "
                f"file_name: {space.metadata.file_name}, "
                f"layout_key: {space.metadata.layout_key}"
            )
```

### Data Group - Custom

Custom Data Groups give you full control over how multiple data units are arranged in the Label Editor.

Unlike grid or carousel layouts (which use ordered lists of UUIDs), custom layouts use keys:

* Map keys to data unit UUIDs.

* Build a layout tree that references those keys and defines:

  * Split direction ("row" or "column")

  * Space split ("splitPercentage")

  * Where each tile (data unit) appears in the Label Editor

<Info>
  Custom Data Groups can be configured using plain Python dictionaries or ORMs.

  * **Using Python dictionaries** — a lightweight, flexible approach
  * **Using ORMs** — a more structured approach with stronger typing and validation

  Both approaches are functionally equivalent. Choose the one that best fits your workflow.
</Info>

<AccordionGroup>
  <Accordion title="Custom Data Groups Details">
    To create a custom data group, you must define a **layout**, **layout contents**, and (optionally) **settings**. These components work together to control how data units are displayed and behave.

    **1. Define the layout structure**

    The layout defines how the Label Editor is split and which data units appear in each section.
    Layouts are expressed as a tree of containers and data unit tiles.

    <CodeGroup>
      ```python Using ORMs theme={"dark"}
      from encord.orm.group_layout import DataUnitTile, LayoutGrid

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

      ```

      ```python Using Dictionaries theme={"dark"}
      layout = {
          "direction": "row",
          "first": {"type": "data_unit", "key": "instructions"},
          "second": {"type": "data_unit", "key": "image"},
          "splitPercentage": 30,
      }
      ```
    </CodeGroup>

    **2. Provide layout contents**

    `layout_contents` maps each layout key to a data unit UUID.
    Every key referenced in the layout **must** be defined here.

    <CodeGroup>
      ```python Using ORMs theme={"dark"}
      from uuid import UUID

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

      ```

      ```python Using Dictionaries theme={"dark"}
      from uuid import UUID

      layout_contents = {
          "instructions": UUID("00000000-0000-0000-0000-000000000000"),
          "image": UUID("11111111-1111-1111-1111-111111111111"),
      }
      ```
    </CodeGroup>

    **3. (Optional) Configure tile settings**

    Tile settings let you control behavior such as making a tile read-only.
    Settings reference the same keys used in the layout.

    <CodeGroup>
      ```python Using ORMs theme={"dark"}
      from encord.orm.group_layout import LayoutSettings, TileSettings

      settings = LayoutSettings(
      tile_settings={
      "instructions": TileSettings(is_read_only=True)
      }
      )

      ```

      ```python Using Dictionaries theme={"dark"}
      settings = {
          "tile_settings": {
              "instructions": {"is_read_only": True}
          }
      }
      ```
    </CodeGroup>

    **4. Create the Data Group**

    Finally, create the Data Group by passing the layout, layout contents, and settings.

    <CodeGroup>
      ```python Using ORMs theme={"dark"}
      from encord.orm.storage import DataGroupCustom

      group = folder.create_data_group(
      DataGroupCustom(
      name="my group",
      layout_contents=layout_contents,
      layout=layout,
      settings=settings,
      )
      )

      ```

      ```python Using Dictionaries theme={"dark"}
      group = folder.create_data_group(
          {
              "name": "my group",
              "layout_contents": layout_contents,
              "layout": layout,
              "settings": settings,
          }
      )
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Custom Data Group Examples">
    <Tabs>
      <Tab title="Example: 2-panel split">
        A simple layout: left panel (instructions) and right panel (image).

        ![Simple Custom Layout](https://storage.googleapis.com/docs-media.encord.com/static/img/data-group-custom-simple.png)

        <CodeGroup>
          ```python Using ORMs theme={"dark"}
          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
          }

          settings = LayoutSettings(
              tile_settings={
                  "instructions": TileSettings(is_read_only=True)
              }
          )

          group = folder.create_data_group(
              DataGroupCustom(
                  name="example-custom-group",
                  layout=layout,
                  layout_contents=layout_contents,
                  client_metadata={"key": "value"},
                  settings=settings,
              )
          )

          # Add all the data groups in a folder to a Dataset
          group_items = folder.list_items(item_types=[StorageItemType.GROUP])
          d = user_client.get_dataset(DATASET_ID)
          d.link_items([item.uuid for item in group_items])

          # Add the Dataset with the Data Groups to a Project

          p = user_client.get_project(PROJECT_ID)
          rows = p.list_label_rows_v2()
          ```

          ```python Using Python Dictionaries theme={"dark"}
          from uuid import UUID

          from encord.constants.enums import DataType
          from encord.orm.storage import DataGroupCustom, StorageItemType
          from encord.user_client import EncordUserClient

          # --- 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 = {
              "direction": "row",
              "first": {"type": "data_unit", "key": "instructions"},
              "second": {"type": "data_unit", "key": "image"},
              "splitPercentage": 30,  # 30% for "instructions", 70% for "image"
          }

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

          settings = {
              "tile_settings": {
                  "instructions": {"is_read_only": True},
              }
          }

          group = folder.create_data_group(
              DataGroupCustom(
                  name="example-custom-group",
                  layout=layout,
                  layout_contents=layout_contents,
                  client_metadata={"key": "value"},
                  settings=settings,
              )
          )

          # Add all the data groups in a folder to a Dataset
          group_items = folder.list_items(item_types=[StorageItemType.GROUP])
          d = user_client.get_dataset(DATASET_ID)
          d.link_items([item.uuid for item in group_items])

          # Add the Dataset with the Data Groups to a Project

          p = user_client.get_project(PROJECT_ID)
          rows = p.list_label_rows_v2()
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Example: Instructions + 2×2 grid layout">
        This example:

        * Uses a column layout overall.

        * Shows "instructions" (a text data unit) at the top (20% height, read-only).

        * Underneath "instructions", a 2×2 grid of videos:

          * Row 1: "top-left" | "top-right"

          * Row 2: "bottom-left" | "bottom-right"

        ![Custom Data Group](https://storage.googleapis.com/docs-media.encord.com/static/img/data-group-custom-layout.png)

        <CodeGroup>
          ```python Using ORMs theme={"dark"}

          from uuid import UUID

          from encord.constants.enums import DataType
          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

          # --- 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)

          # --- Reusable layout and settings ---
          layout = LayoutGrid(
              direction="column",
              first=DataUnitTile(key="instructions"),
              second=LayoutGrid(
                  direction="column",
                  first=LayoutGrid(
                      direction="row",
                      first=DataUnitTile(key="top-left"),
                      second=DataUnitTile(key="top-right"),
                      split_percentage=50,
                  ),
                  second=LayoutGrid(
                      direction="row",
                      first=DataUnitTile(key="bottom-left"),
                      second=DataUnitTile(key="bottom-right"),
                      split_percentage=50,
                  ),
                  split_percentage=50,
              ),
              split_percentage=20,
          )

          settings = LayoutSettings(
              tile_settings={
                  "instructions": TileSettings(is_read_only=True)
              }
          )

          # --- Group definitions (name + UUIDs) ---
          groups = [
              {
                  "name": "group-001",
                  "uuids": {
                      "instructions": UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID. This data unit appears at the top of the Label Editor.
                      "top-left": UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
                      "top-right": UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
                      "bottom-left": UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
                      "bottom-right": UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
                  },
              },
              {
                  "name": "group-002",
                  "uuids": {
                      "instructions": UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID. This data unit appears at the top of the Label Editor.
                      "top-left": UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
                      "top-right": UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
                      "bottom-left": UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
                      "bottom-right": UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
                  },
              },
              {
                  "name": "group-003",
                  "uuids": {
                      "instructions": UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID. This data unit appears at the top of the Label Editor.
                      "top-left": UUID("23232323-2323-2323-2323-232323232323"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
                      "top-right": UUID("31313131-3131-3131-3131-313131313131"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
                      "bottom-left": UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
                      "bottom-right": UUID("56565656-6565-5656-6565-656565656565 "), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
                  },
              },
              # More groups...
          ]

          # Create the Data Groups

          for g in groups:
              group = folder.create_data_group(
                  DataGroupCustom(
                      name=g["name"],
                      layout=layout,
                      layout_contents=g["uuids"],
                      settings=settings,
                  )
              )
              print(f"✅ Created group '{g['name']}' with UUID {group}")

          # Add all the data groups in a folder to a Dataset
          group_items = folder.list_items(item_types=[StorageItemType.GROUP])
          d = user_client.get_dataset(DATASET_ID)
          d.link_items([item.uuid for item in group_items])

          # Add the Dataset with the Data Groups to a Project

          p = user_client.get_project(PROJECT_ID)
          rows = p.list_label_rows_v2()

          # Data Group labels are accessed through the parent row's Label Spaces
          for row in rows:
              if row.data_type == DataType.GROUP:
                  row.initialise_labels()
                  for space in row.get_spaces():
                      print(
                          f"space_id: {space.space_id}, "
                          f"file_name: {space.metadata.file_name}, "
                          f"layout_key: {space.metadata.layout_key}"
                      )

          ```

          ```python Using Python Dictionaries theme={"dark"}

          from uuid import UUID

          from encord.constants.enums import DataType
          from encord.orm.storage import DataGroupCustom, StorageItemType
          from encord.user_client import EncordUserClient

          # --- 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)

          # --- Reusable layout and settings ---
          layout = {
              "direction": "column",
              "first": {"type": "data_unit", "key": "instructions"},
              "second": {
                  "direction": "column",
                  "first": {
                      "direction": "row",
                      "first": {"type": "data_unit", "key": "top-left"},
                      "second": {"type": "data_unit", "key": "top-right"},
                      "splitPercentage": 50,
                  },
                  "second": {
                      "direction": "row",
                      "first": {"type": "data_unit", "key": "bottom-left"},
                      "second": {"type": "data_unit", "key": "bottom-right"},
                      "splitPercentage": 50,
                  },
                  "splitPercentage": 50,
              },
              "splitPercentage": 20,
          }
          settings = {"tile_settings": {"instructions": {"is_read_only": True}}}

          # --- Group definitions (name + UUIDs) ---
          groups = [
              {
                  "name": "group-001",
                  "uuids": {
                      "instructions": UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID. This data unit appears at the top of the Label Editor.
                      "top-left": UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
                      "top-right": UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
                      "bottom-left": UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
                      "bottom-right": UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
                  },
              },
              {
                  "name": "group-002",
                  "uuids": {
                      "instructions": UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID. This data unit appears at the top of the Label Editor.
                      "top-left": UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
                      "top-right": UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
                      "bottom-left": UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
                      "bottom-right": UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
                  },
              },
              {
                  "name": "group-003",
                  "uuids": {
                      "instructions": UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID. This data unit appears at the top of the Label Editor.
                      "top-left": UUID("23232323-2323-2323-2323-232323232323"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
                      "top-right": UUID("31313131-3131-3131-3131-313131313131"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
                      "bottom-left": UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
                      "bottom-right": UUID("56565656-6565-5656-6565-656565656565 "), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
                  },
              },
              # More groups...
          ]

          # Create the Data Groups

          for g in groups:
              group = folder.create_data_group(
                  DataGroupCustom(
                      name=g["name"],
                      layout=layout,
                      layout_contents=g["uuids"],
                      settings=settings,
                  )
              )
              print(f"✅ Created group '{g['name']}' with UUID {group}")

          # Add all the data groups in a folder to a Dataset
          group_items = folder.list_items(item_types=[StorageItemType.GROUP])
          d = user_client.get_dataset(DATASET_ID)
          d.link_items([item.uuid for item in group_items])

          # Add the Dataset with the Data Groups to a Project

          p = user_client.get_project(PROJECT_ID)
          rows = p.list_label_rows_v2()

          # Data Group labels are accessed through the parent row's Label Spaces
          for row in rows:
              if row.data_type == DataType.GROUP:
                  row.initialise_labels()
                  for space in row.get_spaces():
                      print(
                          f"space_id: {space.space_id}, "
                          f"file_name: {space.metadata.file_name}, "
                          f"layout_key: {space.metadata.layout_key}"
                      )

          ```
        </CodeGroup>
      </Tab>

      <Tab title="Example Carousel-style in a Grid-style">
        This example inserts a carousel-style Data Group inside a grid-style Data Group.

        <CodeGroup>
          ```python Custom Carousel-style in Grid-style theme={"dark"}

          from uuid import UUID

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

          # User Input

          SSH_PATH = "/path/to/your/encord_private_key.txt"
          FOLDER_ID = "00000000-0000-0000-0000-000000000000"
          GROUP_NAME = "carousel-inside-grid"

          # --- 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)

          # Replace these with real file UUIDs
          LAYOUT_CONTENTS = {
              "g1": UUID("11111111-1111-1111-1111-111111111111"),
              "g2": UUID("22222222-2222-2222-2222-222222222222"),
              "g3": UUID("33333333-3333-3333-3333-333333333333"),
              "g4": UUID("44444444-4444-4444-4444-444444444444"),
              "g5": UUID("55555555-5555-5555-5555-555555555555"),
              "g6": UUID("66666666-6666-6666-6666-666666666666"),
              "g7": UUID("77777777-7777-7777-7777-777777777777"),
              "g8": UUID("88888888-8888-8888-8888-888888888888"),
              "g9": UUID("99999999-9999-9999-9999-999999999999"),
              "c1": UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"),
              "c2": UUID("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"),
              "c3": UUID("cccccccc-cccc-cccc-cccc-cccccccccccc"),
              "c4": UUID("dddddddd-dddd-dddd-dddd-dddddddddddd"),
          }

          # 3x3 grid on the left
          row_1 = LayoutGrid(
              direction="row",
              first=DataUnitTile(key="g1"),
              second=LayoutGrid(
                  direction="row",
                  first=DataUnitTile(key="g2"),
                  second=DataUnitTile(key="g3"),
                  split_percentage=50,
              ),
              split_percentage=33,
          )

          row_2 = LayoutGrid(
              direction="row",
              first=DataUnitTile(key="g4"),
              second=LayoutGrid(
                  direction="row",
                  first=DataUnitTile(key="g5"),
                  second=DataUnitTile(key="g6"),
                  split_percentage=50,
              ),
              split_percentage=33,
          )

          row_3 = LayoutGrid(
              direction="row",
              first=DataUnitTile(key="g7"),
              second=LayoutGrid(
                  direction="row",
                  first=DataUnitTile(key="g8"),
                  second=DataUnitTile(key="g9"),
                  split_percentage=50,
              ),
              split_percentage=33,
          )

          grid_3x3 = LayoutGrid(
              direction="column",
              first=row_1,
              second=LayoutGrid(
                  direction="column",
                  first=row_2,
                  second=row_3,
                  split_percentage=50,
              ),
              split_percentage=33,
          )

          # Carousel on the right
          carousel_panel = DataUnitCarouselTile(
              keys=["c1", "c2", "c3", "c4"],
              carousel_position="right",
              carousel_size=25,
          )

          # Final layout
          layout = LayoutGrid(
              direction="row",
              first=grid_3x3,
              second=carousel_panel,
              split_percentage=78,
          )

          settings = LayoutSettings(fixed_layout=True)

          group_uuid = folder.create_data_group(
              DataGroupCustom(
                  name=GROUP_NAME,
                  layout=layout,
                  layout_contents=LAYOUT_CONTENTS,
                  settings=settings,
              )
          )

          print(f"Created data group: {group_uuid}")

          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## Get Data Group Data Units

Use the following to get the data units that comprise a Data Group.

<CodeGroup>
  ```python Data Groups - Get Child IDs from Storage Folder theme={"dark"}

  from encord import EncordUserClient

  SSH_PATH="/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
  DATA_GROUP_ID="00000000-0000-0000-0000-000000000000" # Replace with the file ID for the Data Group

  # Initialize the SDK client
  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",
  )

  # Fetch the Data Group as a storage item
  data_group_item = user_client.get_storage_item(DATA_GROUP_ID)

  print(f"Data Group: {data_group_item.name} ({data_group_item.uuid})")

  for item in data_group_item.get_child_items():
      print(f"- UUID: {item.uuid}, Name: {item.name}")

  ```

  ```python Data Groups - Get Child IDs from Dataset theme={"dark"}

  from encord import EncordUserClient
  from uuid import UUID

  SSH_PATH="/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
  DATA_GROUP_ID="00000000-0000-0000-0000-000000000000" # Replace with the file ID for the Data Group
  DATASET_ID="00000000-0000-0000-0000-000000000000" # Replace with the ID for the Dataset

  # Initialize the SDK client
  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",
  )

  # Data Group
  data_group_item = user_client.get_storage_item(DATA_GROUP_ID)
  children = list(data_group_item.get_child_items())

  # Dataset rows
  dataset = user_client.get_dataset(DATASET_ID)
  rows = list(dataset.list_data_rows())
  rows_by_backing = {}
  for r in rows:
      try:
          # Normalize to UUID for robust matching
          if r.backing_item_uuid is not None:
              rows_by_backing[UUID(str(r.backing_item_uuid))] = r
      except Exception:
          pass  # ignore malformed ids

  # Print header + ALL children in the group
  print(f"Data Group: {data_group_item.name} ({data_group_item.uuid})")
  for it in children:
      _row = rows_by_backing.get(UUID(str(it.uuid)))
      print(f"- UUID: {it.uuid}, Name: {it.name}")
      
  ```
</CodeGroup>

## Get Data Group Information

Use the following script to view:

* Group layout contents
* Group layout
* Group layout settings

```python Data Group Summary theme={"dark"}
from encord import EncordUserClient
from encord.orm.storage import StorageItemType

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "b95caa81-931a-4da9-b784-64037699f9fc"  # 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)

# Get Data Group Info
first_group = list(folder.list_items(item_types=[StorageItemType.GROUP]))[0]
summary = first_group.get_summary()
assert summary.data_group is not None
print(summary.data_group.layout_contents)
print(summary.data_group.layout)
print(summary.data_group.layout_settings)
```

## Multi-Layer Data Groups

Multi-Layer Data Groups allow you to apply labels across all data units in a group simultaneously. Any label added or edited in the Label Editor is automatically applied to every data unit in the group. These shared labels are exported under the `root` key, which contains all label information that applies to the Data Group as a whole.

To create a Multi-Layer Data Group, set `has_multilayer_labels=True` in the group settings when [creating a custom Data Group](/sdk-documentation/index-sdk/sdk-data-groups#data-group-custom):

```python theme={"dark"}
from encord.orm.group_layout import LayoutSettings, TileSettings

settings = LayoutSettings(
    tile_settings={
        "instructions": TileSettings(is_read_only=True)
    },
    has_multilayer_labels=True
)
```

## Read-Only Tiles

You can mark individual tiles in a Data Group as read-only. Annotators can view a read-only tile in the Label Editor but cannot add labels to it. This is useful for tiles that provide reference context — such as an instructions document or a reference camera feed — that annotators should see but not annotate.

The `is_read_only` flag lives in `settings.tile_settings` in the manifest JSON, keyed by tile name. When you serialize a Data Group, Encord projects the per-tile read-only flag into `settings.tile_settings` automatically.

**Manifest JSON example**

```json theme={"dark"}
{
  "version": "1.0",
  "data_groups": [
    {
      "id": "group-1",
      "name": "Group 1",
      "layout_type": "default-grid",
      "members": {
        "camera_left": { "simple_pattern": "left/*.png" },
        "camera_right": { "simple_pattern": "right/*.png" }
      },
      "settings": {
        "tile_settings": {
          "camera_left": { "is_read_only": true }
        }
      }
    }
  ]
}
```

**SDK example**

```python theme={"dark"}
from encord.orm.group_layout import LayoutSettings, TileSettings

settings = LayoutSettings(
    tile_settings={
        "instructions": TileSettings(is_read_only=True)
    }
)
```

<Note>
  The read-only flag round-trips correctly through manifest import and export. Renaming a tile preserves its read-only flag. Deleting a read-only tile removes the flag cleanly from the manifest.
</Note>


# Files and Folders
Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-files-and-folders



## Cloud-Synced Folders

Cloud-synced folders automatically stay in sync with connected cloud storage, regularly updating to ensure all new and existing files are available in Encord without manual intervention. Cloud-synced Folders require that you have at least one integration set up.

* Cloud-synced folders support images, videos, PDFs, text, HTML, and audio files.

<Note>Image groups, image sequences, and DICOM series are not currently supported by Cloud-synced folders.</Note>

* A single cloud synced folder can contain a maximum of 10 million files.

### Create a Cloud-synced Folder

```python Create Cloud-synced Folder theme={"dark"}
from uuid import UUID
from encord import EncordUserClient
from encord.orm.storage import CloudSyncedFolderParams

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Specify the file path to your access key
CLOUD_SYNCED_FOLDER_NAME = "SDK Cloud-Synced Folder" # Specify a meaningful name for your Cloud-synced Folder
CLOUD_SYNCED_FOLDER_DESCRIPTION = "A folder to store my files" # Specify a meaningful description for your Cloud-synced Folder
INTEGRATION_UUID = "3b6299c3-f8c8-4755-ae26-d9144b215920" # Specify the unique id for your integration
REMOTE_URL = "gs://my-gcp-bucket/" # Specify the storage/file path to your cloud storage

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    domain="https://api.encord.com",
)

# Create cloud synced folder params
cloud_synced_folder_params = CloudSyncedFolderParams(
    integration_uuid=UUID(INTEGRATION_UUID),
    remote_url=REMOTE_URL,
)

# Create the storage folder
folder_name = CLOUD_SYNCED_FOLDER_NAME
folder_description = CLOUD_SYNCED_FOLDER_DESCRIPTION
folder_metadata = {"my": "folder_metadata"}

storage_folder = user_client.create_storage_folder(
    name=folder_name,
    description=folder_description,
    client_metadata=folder_metadata,
    cloud_synced_folder_params=cloud_synced_folder_params,
)
```

## Sync Cloud-synced Folder with Cloud Storage

The following code syncs a Cloud-sync Folder with the cloud storage bucket.

The `sync_private_data_with_cloud_synced_folder_get_result` time out value can be adjusted to your needs.

```python Sync Cloud-synced Folder theme={"dark"}

from uuid import UUID

from encord import EncordUserClient
from encord.orm.storage import SyncPrivateDataWithCloudSyncedFolderStatus

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Specify the file path to your access key
CLOUD_SYNCED_FOLDER_UUID = UUID("7270fb4a-fc8a-4336-b8dd-5b548d27889d")

# Authenticate with Encord

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    domain="https://api.encord.com",
)


# Get folder by UUID 
storage_folder = user_client.get_storage_folder(CLOUD_SYNCED_FOLDER_UUID)
print(f"Using cloud-synced folder uuid={storage_folder.uuid}")

# Start sync job

sync_job_uuid = storage_folder.sync_private_data_with_cloud_synced_folder_start()
print(f"Started sync job: {sync_job_uuid}")

# Poll for result
result = storage_folder.sync_private_data_with_cloud_synced_folder_get_result(
    sync_job_uuid,
    timeout_seconds=300,  # adjust as needed
)

print(f"Sync job finished with status: {result.status}")

# Handle result
if result.status == SyncPrivateDataWithCloudSyncedFolderStatus.DONE:
    print("Sync completed (server finished the job).")

    any_errors = (
        result.scan_pages_processing_error > 0
        or result.upload_jobs_error > 0
        or result.upload_jobs_units_error > 0
    )

    print("Progress summary:")
    print(
        f"  Bucket listing pages: "
        f"pending={result.scan_pages_processing_pending}, "
        f"done={result.scan_pages_processing_done}, "
        f"error={result.scan_pages_processing_error}, "
        f"cancelled={result.scan_pages_processing_cancelled}"
    )
    print(
        f"  Upload jobs: "
        f"pending={result.upload_jobs_pending}, "
        f"done={result.upload_jobs_done}, "
        f"error={result.upload_jobs_error}"
    )
    print(
        f"  File units: "
        f"pending={result.upload_jobs_units_pending}, "
        f"done={result.upload_jobs_units_done}, "
        f"error={result.upload_jobs_units_error}, "
        f"cancelled={result.upload_jobs_units_cancelled}"
    )

    if any_errors:
        print("Sync finished, but some parts failed. Inspect the *_error counters above.")
    else:
        print("Sync finished successfully with no reported errors.")

elif result.status == SyncPrivateDataWithCloudSyncedFolderStatus.PENDING:
    print("Sync is still in progress. Try polling again later.")

elif result.status == SyncPrivateDataWithCloudSyncedFolderStatus.ERROR:
    print("Sync failed (critical error).")

elif result.status == SyncPrivateDataWithCloudSyncedFolderStatus.CANCELLED:
    print("Sync was cancelled.")

else:
    print(f"Unexpected status: {result.status!r}")

```

## Create New Standard Folder

The following script creates a new folder in the root directory of **Data** > **Files & Folders**. Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<folder_name>` with the name you want to give your folder. We recommend using unique folder names.
* Replace `A folder to store my files` with a meaningful description for your folder.
* Replace `my: folder_metadata` with any metadata you want to add to the folder. Remove the line if you do not want to add any metadata to the folder.

<CodeGroup>
  ```python Image theme={"dark"}
  from encord import EncordUserClient

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )



  # Create a storage 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)
  ```
</CodeGroup>

***

## Move Files

Use the following script to move various types of files to a different folder in **Data** > **Files & Folders**. Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<data_unit_name>` with the name of the file you want to move to a new folder.
* Replace `<target_folder_name>` with the name of the folder you want to move the file from.
* Replace `<target_folder_name>` with the name of the folder you want to move the file to.

<CodeGroup>
  ```python Images theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import StorageItemType, FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Define the search criteria for the data unit and folders folder
  START_FOLDER = "<start_folder_name>"
  TARGET_FOLDER = "<target_folder_name>"  
  DATA_UNIT_NAME = "<data_unit_name>"

  # Retrieve the start folder by its name (assuming only one match)
  START_FOLDER = next(user_client.find_storage_folders(search=start_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Retrieve the target folder by its name (assuming only one match)
  TARGET_FOLDER = next(user_client.find_storage_folders(search=target_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Search for the specific data unit using its name, assuming it only returns one result
  item = START_FOLDER.list_items(
      search=DATA_UNIT_NAME,
      is_in_dataset=None,  
      item_types=[StorageItemType.IMAGE],
      order=FoldersSortBy.NAME,
      desc=False,
      get_signed_urls=False,
      page_size=1000  # Expecting only one data unit
  )

  # Move the found data unit to the retrieved target folder
  print(f"Moving item {item.uuid} to folder {TARGET_FOLDER.uuid}")
  item.move_to_folder(TARGET_FOLDER.uuid)
  ```

  ```python Video theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import StorageItemType, FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Define the search criteria for the data unit and folders folder
  START_FOLDER = "<start_folder_name>"
  TARGET_FOLDER = "<target_folder_name>"  
  DATA_UNIT_NAME = "<data_unit_name>"

  # Retrieve the start folder by its name (assuming only one match)
  START_FOLDER = next(user_client.find_storage_folders(search=start_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Retrieve the target folder by its name (assuming only one match)
  TARGET_FOLDER = next(user_client.find_storage_folders(search=target_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Search for the specific data unit using its name, assuming it only returns one result
  item = START_FOLDER.list_items(
      search=DATA_UNIT_NAME,
      is_in_dataset=None,  
      item_types=[StorageItemType.VIDEO],
      order=FoldersSortBy.NAME,
      desc=False,
      get_signed_urls=False,
      page_size=1000  # Expecting only one data unit
  )

  # Move the found data unit to the retrieved target folder
  print(f"Moving item {item.uuid} to folder {TARGET_FOLDER.uuid}")
  item.move_to_folder(TARGET_FOLDER.uuid)
  ```

  ```python Image group theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import StorageItemType, FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Define the search criteria for the data unit and folders folder
  START_FOLDER = "<start_folder_name>"
  TARGET_FOLDER = "<target_folder_name>"  
  DATA_UNIT_NAME = "<data_unit_name>"

  # Retrieve the start folder by its name (assuming only one match)
  START_FOLDER = next(user_client.find_storage_folders(search=start_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Retrieve the target folder by its name (assuming only one match)
  TARGET_FOLDER = next(user_client.find_storage_folders(search=target_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Search for the specific data unit using its name, assuming it only returns one result
  item = START_FOLDER.list_items(
      search=DATA_UNIT_NAME,
      is_in_dataset=None,  
      item_types=[StorageItemType.IMAGE_GROUP],
      order=FoldersSortBy.NAME,
      desc=False,
      get_signed_urls=False,
      page_size=1000  # Expecting only one data unit
  )

  # Move the found data unit to the retrieved target folder
  print(f"Moving item {item.uuid} to folder {TARGET_FOLDER.uuid}")
  item.move_to_folder(TARGET_FOLDER.uuid)
  ```

  ```python Image sequence theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import StorageItemType, FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Define the search criteria for the data unit and folders folder
  START_FOLDER = "<start_folder_name>"
  TARGET_FOLDER = "<target_folder_name>"  
  DATA_UNIT_NAME = "<data_unit_name>"

  # Retrieve the start folder by its name (assuming only one match)
  START_FOLDER = next(user_client.find_storage_folders(search=start_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Retrieve the target folder by its name (assuming only one match)
  TARGET_FOLDER = next(user_client.find_storage_folders(search=target_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Search for the specific data unit using its name, assuming it only returns one result
  item = START_FOLDER.list_items(
      search=DATA_UNIT_NAME,
      is_in_dataset=None,  
      item_types=[StorageItemType.IMAGE_SEQUENCE],
      order=FoldersSortBy.NAME,
      desc=False,
      get_signed_urls=False,
      page_size=1000  # Expecting only one data unit
  )

  # Move the found data unit to the retrieved target folder
  print(f"Moving item {item.uuid} to folder {TARGET_FOLDER.uuid}")
  item.move_to_folder(TARGET_FOLDER.uuid)
  ```

  ```python DICOM series  theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import StorageItemType, FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Define the search criteria for the data unit and folders folder
  START_FOLDER = "<start_folder_name>"
  TARGET_FOLDER = "<target_folder_name>"  
  DATA_UNIT_NAME = "<data_unit_name>"

  # Retrieve the start folder by its name (assuming only one match)
  START_FOLDER = next(user_client.find_storage_folders(search=start_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Retrieve the target folder by its name (assuming only one match)
  TARGET_FOLDER = next(user_client.find_storage_folders(search=target_folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Search for the specific data unit using its name, assuming it only returns one result
  item = START_FOLDER.list_items(
      search=DATA_UNIT_NAME,
      is_in_dataset=None,  
      item_types=[StorageItemType.DICOM_SERIES],
      order=FoldersSortBy.NAME,
      desc=False,
      get_signed_urls=False,
      page_size=1000  # Expecting only one data unit
  )

  # Move the found data unit to the retrieved target folder
  print(f"Moving item {item.uuid} to folder {TARGET_FOLDER.uuid}")
  item.move_to_folder(TARGET_FOLDER.uuid)
  ```
</CodeGroup>

***

## Move Folders

You can move folders between different parent folders in **Data** > **Files & Folders**, including moving them to the root (no parent). The following script demonstrates how a folder with the name `Folder Name 3` is moved between 2 different target folders. The script must be modified to suit your needs.

Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `Folder Name 1` with the name of a target folder.
* Replace `Folder Name 2` with the new name of another target folder.
* Replace `Folder Name 3` with the name of the folder that is moved.

```python Folders theme={"dark"}
from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Search for folders by name using the find_storage_folders function
folder_1 = next(user_client.find_storage_folders(search="Folder Name 1", dataset_synced=False, order=FoldersSortBy.NAME, desc=False, page_size=1000))
folder_2 = next(user_client.find_storage_folders(search="Folder Name 2", dataset_synced=False, order=FoldersSortBy.NAME, desc=False, page_size=1000))
folder_3 = next(user_client.find_storage_folders(search="Folder Name 3", dataset_synced=False, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Move folder_3 under folder_1
folder_3.move_to_folder(folder_1.uuid)

# Move folder_3 under folder_2
folder_3.move_to_folder(folder_2.uuid)

# Move folder_3 to root folder (passing None moves it to the root level)
folder_3.move_to_folder(None)
```

## Update URL for Cloud Storage Files

Use the following script to update the cloud storage path of your files in Encord when, for example:

* You move files in cloud storage
* Update your folder structure in cloud storage
* Update URLs to use multi-region access points

```python theme={"dark"}
from encord.utilities.storage.cloud_data_migration import update_storage_item_cloud_info
from uuid import UUID
from encord import EncordUserClient

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Specify the file path to your access key for authentication
FILE_ID = "11984de7-3690-4f6e-a317-8ee1ef4a926b" # Specify the File ID for the file
NEW_URL_01 = "https://storage.cloud.google.com/my-gcp-bucket/Move_Data_Unit/my-video-01.mp4" # Specify the new URL for the file

# Authentication
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",
)

# Define the UUID of the item to update, or use its URL
item_uuid = UUID(FILE_ID)

# New URL after the file was moved
new_url = NEW_URL_01

# Update the storage item with the new URL, skip missing items
update_storage_item_cloud_info(
    user_client=user_client,
    item=item_uuid,  # or the URL of the item
    new_url=new_url,
    verify_access=True,
     skip_missing=True )

print("Successfully updated storage item with new URL.")
```

***

## Change Cloud Storage Provider

Using the SDK you can change from one cloud storage provider (for example AWS) to another cloud storage provider (for example GCP) while maintaining data integrity.

<iframe title="YouTube video player" />

```python Change Cloud Storage Provider theme={"dark"}

from encord import EncordUserClient
from uuid import UUID
from encord.http.bundle import Bundle
from encord.storage import StorageItem
from encord.utilities.storage.cloud_data_migration import update_storage_item_cloud_info

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
EXISTING_INTEGRATION_ID = "00000000-0000-0000-0000-000000000000" # Replace with the integration ID of source cloud storage integration
NEW_INTEGRATION_ID = "00000000-0000-0000-0000-000000000000" # Replace with the integration ID of the destination cloud storage integration
STORAGE_FOLDER_HASH = "00000000-0000-0000-0000-000000000000" # Replace with the folder ID where the data resides
OLD_BUCKET_NAME_AND_FOLDER = "s3://aws-bucket-001/folder-001/" # Replace with the storage path of the source cloud storage bucket and folder
NEW_BUCKET_NAME_AND_FOLDER = "gs://gcp-bucket-01/" # Replace with the storage path of the destination cloud storage bucket and folder


# Create user client using access key
encord_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",
)

storage_folder = encord_client.get_storage_folder(STORAGE_FOLDER_HASH)


# function to determine new URL
def create_new_url(existing_url: str) -> str:
    return existing_url.replace(OLD_BUCKET_NAME_AND_FOLDER, NEW_BUCKET_NAME_AND_FOLDER)

# Get item UUIDs
item_uuids = [item.uuid for item in storage_folder.list_items()]

# Compare before and after
items_before = encord_client.get_storage_items(item_uuids, sign_url=False)
assert all(str(item.integration_hash) == EXISTING_INTEGRATION_ID for item in items_before)

with Bundle() as bundle:
    for item in items_before:
        update_storage_item_cloud_info(
            encord_client,
            item,
            from_cloud_integration=EXISTING_INTEGRATION_ID,
            new_cloud_integration=NEW_INTEGRATION_ID,
            new_url=create_new_url(item.url),
            verify_access=True,
            bundle=bundle,
        )

items_after = encord_client.get_storage_items(item_uuids, sign_url=False)

assert len(items_after) == len(items_before)
assert all(str(item.integration_hash) == NEW_INTEGRATION_ID for item in items_after)

# Verify the migration worked
for item in storage_folder.list_items():
  print(f"url: {item.url}")
  print(f"integration: {item.integration_hash}")

```

***

## Update Folder Properties

Use the following script to update the name and description of an existing folder in **Data** > **Files & Folders**. Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `Cat Videos` with the name of the folder you want to update properties for.
* Replace `Cat videos and images` with the new name you want to give the folder.
* Replace `Images and videos of cats` with the description you want to give the folder.

<Tip>Use the [list\_storage\_folders]() and find\_storage\_folders methods to search for specific folders. </Tip>

<Tip>If you are updating many folders at once, pass a [Bundle](/sdk-documentation/sdk-references/http.bundle) to `folder.update` to batch the changes into a single server call. See [Bulk Action Best Practices](/sdk-documentation/general-sdk/sdk-bulk-action-best-practices) and keep bundle sizes under 1000 operations.</Tip>

<CodeGroup>
  ```python Single folder theme={"dark"}
  from encord import EncordUserClient
  from encord.orm.storage import FoldersSortBy

  # Instantiate Encord client using your SSH private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Define search parameters
  folder_name_to_find = "Cat Videos"
  search_result = user_client.find_storage_folders(
      search=folder_name_to_find,
      dataset_synced=None,
      order=FoldersSortBy.NAME,
      desc=False,
      page_size=1000
  )

  # Fetch the folder assuming it's the first one in the search result
  folder = next(search_result, None)
  if folder is None:
      print(f"No folder found with name {folder_name_to_find}")
  else:
      # Define new properties for the folder
      new_name = "Cat videos and images"
      new_description = "Images and videos of cats"

      # Update the folder properties
      folder.update(name=new_name, description=new_description)
      print(f"Folder '{folder_name_to_find}' updated to new name '{new_name}' and description '{new_description}'")
  ```

  ```python Bulk update (Bundle) theme={"dark"}
  from encord import EncordUserClient
  from encord.orm.storage import FoldersSortBy

  # Instantiate Encord client using your SSH private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Map current folder names to the new properties you want to apply.
  folder_updates = {
      "Cat Videos": {
          "name": "Cat videos and images",
          "description": "Images and videos of cats",
      },
      "Dog Videos": {
          "name": "Dog videos and images",
          "description": "Images and videos of dogs",
      },
  }

  # Collect folders first so the search calls are not bundled.
  folders_to_update = []

  for folder_name, new_props in folder_updates.items():
      folder = next(
          user_client.find_storage_folders(
              search=folder_name,
              dataset_synced=None,
              order=FoldersSortBy.NAME,
              desc=False,
              page_size=1000,
          ),
          None,
      )

      if folder is None:
          print(f"No folder found with name '{folder_name}'")
          continue

      folders_to_update.append((folder, folder_name, new_props))

  # Apply all updates using bundled requests.
  with user_client.create_bundle(bundle_size=1000) as bundle:
      for folder, old_folder_name, new_props in folders_to_update:
          folder.update(
              name=new_props["name"],
              description=new_props["description"],
              bundle=bundle,
          )

          print(
              f"Queued update for '{old_folder_name}' -> "
              f"'{new_props['name']}' with description "
              f"'{new_props['description']}'"
          )

  print("Bundled folder updates executed.")
  ```
</CodeGroup>

***

## Delete Folders

Use the following script to delete a specific folder from **Data** > **Files & Folders**. Ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `Specific Folder Name` with the name of the folder you want to delete.

```python theme={"dark"}
from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Define the search criteria for the folder
folder_search_criteria = "Specific Folder Name"

# Retrieve the target folder
try:
    folder_to_delete = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))
    print(f"Deleting folder {folder_to_delete.uuid}")

    # Delete the folder and verify it cannot be accessed anymore
    folder_to_delete.delete()
    print("Folder deleted successfully.")

    try:
        # Try to refetch the folder to verify it's been deleted
        user_client.get_storage_folder(folder_to_delete.uuid)
        print("Error: Folder still accessible after deletion.")
    except Exception as e:
        print(f"Verification successful: {str(e)}")

except StopIteration:
    print("No folder found with the specified criteria.")
```


# Image Groups and Image Sequences
Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-image-groups-image-sequences

Learn how to create Image Groups and Image Sequences in Encord using the SDK.

Image groups can consist of images with different dimensions. In contrast, image sequences are images that all have the same dimensions. When images of varying dimensions are grouped together, multiple image sequences are created, each containing files that share the same dimensions.

## Create Image Groups

**From Existing Files**

<CodeGroup>
  ```python Create Image Groups - Basic expandable theme={"dark"}

  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 Create Image Groups - Advanced expandable theme={"dark"}

  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}"
      )
  ```
</CodeGroup>

**From Local Files**

<CodeGroup>
  ```python Create Image Groups from Items - Basic expandable theme={"dark"}

  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus
  from encord.orm.storage import DataUploadImageGroupFromItems
  from encord.storage import DataUploadItems

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  storage_folder = user_client.get_storage_folder("<folder_hash>")

  image_group = DataUploadImageGroupFromItems(
      image_items=[
          "11111111-1111-1111-1111-111111111111",
          "22222222-2222-2222-2222-222222222222",
          "33333333-3333-3333-3333-333333333333",
      ],
      title="My Image Group",
  )

  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id="<integration_id>",
      private_files=DataUploadItems(
          image_groups_from_items=[image_group]
      ),
  )

  result = storage_folder.add_private_data_to_folder_get_result(upload_job_id)

  if result.status == LongPollingStatus.DONE:
      print("Image group created successfully!")
  ```

  ```python Create Image Groups from Items - Advanced expandable theme={"dark"}

  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus
  from encord.orm.storage import DataUploadImageGroupFromItems
  from encord.storage import DataUploadItems

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

  # --- Connect to Encord ---
  user_client = 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",
  )

  storage_folder = user_client.get_storage_folder(FOLDER_ID)

  image_groups = [
      DataUploadImageGroupFromItems(
          image_items=[
              "11111111-1111-1111-1111-111111111111",
              "22222222-2222-2222-2222-222222222222",
              "33333333-3333-3333-3333-333333333333",
          ],
          title="vehicle-inspection-001",
          client_metadata={
              "inspection_id": "001",
              "vehicle_type": "car",
          },
      ),
      DataUploadImageGroupFromItems(
          image_items=[
              "44444444-4444-4444-4444-444444444444",
              "55555555-5555-5555-5555-555555555555",
              "66666666-6666-6666-6666-666666666666",
          ],
          title="vehicle-inspection-002",
          client_metadata={
              "inspection_id": "002",
              "vehicle_type": "truck",
          },
      ),
  ]

  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id=INTEGRATION_ID,
      private_files=DataUploadItems(
          image_groups_from_items=image_groups,
      ),
  )

  result = storage_folder.add_private_data_to_folder_get_result(upload_job_id)

  if result.status == LongPollingStatus.DONE:
      print(f"Successfully created {len(image_groups)} image groups.")
  ```
</CodeGroup>

## Create Image Sequences

**From Existing Files**

<CodeGroup>
  ```python Create Image Sequences - Basic expandable theme={"dark"}

  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 Create Image Sequences - Advanced expandable theme={"dark"}

  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}"
      )
  ```
</CodeGroup>

**From Local Files**

<CodeGroup>
  ```python Create Image Sequences from Items - Basic expandable theme={"dark"}

  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus
  from encord.orm.storage import DataUploadImageGroupFromItems
  from encord.storage import DataUploadItems

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

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

  storage_folder = user_client.get_storage_folder(FOLDER_ID)

  image_sequence = DataUploadImageGroupFromItems(
      image_items=[
          "11111111-1111-1111-1111-111111111111",
          "22222222-2222-2222-2222-222222222222",
          "33333333-3333-3333-3333-333333333333",
      ],
      title="drive-sequence-001",
      create_video=True,
  )

  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id=INTEGRATION_ID,
      private_files=DataUploadItems(
          image_groups_from_items=[image_sequence],
      ),
  )

  result = storage_folder.add_private_data_to_folder_get_result(upload_job_id)

  if result.status == LongPollingStatus.DONE:
      print("Image sequence created successfully.")
  ```

  ```python Create Image Sequences from Items - Advanced expandable theme={"dark"}

  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus
  from encord.orm.storage import DataUploadImageGroupFromItems
  from encord.storage import DataUploadItems

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

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

  storage_folder = user_client.get_storage_folder(FOLDER_ID)

  image_sequences = [
      DataUploadImageGroupFromItems(
          image_items=[
              "11111111-1111-1111-1111-111111111111",
              "22222222-2222-2222-2222-222222222222",
              "33333333-3333-3333-3333-333333333333",
          ],
          title="drive-sequence-001",
          create_video=True,
          client_metadata={
              "sequence_id": "001",
              "scenario": "urban",
          },
      ),
      DataUploadImageGroupFromItems(
          image_items=[
              "44444444-4444-4444-4444-444444444444",
              "55555555-5555-5555-5555-555555555555",
              "66666666-6666-6666-6666-666666666666",
          ],
          title="drive-sequence-002",
          create_video=True,
          client_metadata={
              "sequence_id": "002",
              "scenario": "highway",
          },
      ),
  ]

  upload_job_id = storage_folder.add_private_data_to_folder_start(
      integration_id=INTEGRATION_ID,
      private_files=DataUploadItems(
          image_groups_from_items=image_sequences,
      ),
  )

  result = storage_folder.add_private_data_to_folder_get_result(upload_job_id)

  if result.status == LongPollingStatus.DONE:
      print(f"Successfully created {len(image_sequences)} image sequences.")
  ```
</CodeGroup>

## Create at Scale

For large-scale imports, create image groups and image sequences from a JSON manifest. This is the recommended approach when importing hundreds or thousands of grouped images because it avoids making one SDK request per group.

### Image Groups

<CodeGroup>
  ```python Image Groups at Scale theme={"dark"}

  from pathlib import Path

  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus
  from encord.storage import DataUploadItems

  SSH_PATH = "/path/to/ssh-private-key.txt"
  FOLDER_ID = "00000000-0000-0000-0000-000000000000"
  JSON_FILE = Path("./image-groups.json")

  user_client = 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)

  upload_job_id = folder.add_private_data_to_folder_start(
      DataUploadItems(file_path=JSON_FILE)
  )

  result = folder.add_private_data_to_folder_get_result(
      upload_job_id,
      timeout_seconds=600,
  )

  if result.status == LongPollingStatus.DONE:
      print("Upload complete.")
      print(result)
  else:
      print("Upload did not complete within the timeout.")
      print(result)
  ```

  ```json image-groups.json theme={"dark"}
  {
    "image_groups": [
      {
        "title": "vehicle-inspection-001",
        "createVideo": false,
        "objectUrl_0": "s3://my-bucket/vehicle-001/front.jpg",
        "objectUrl_1": "s3://my-bucket/vehicle-001/side.jpg",
        "objectUrl_2": "s3://my-bucket/vehicle-001/rear.jpg",
        "clientMetadata": {
          "inspection_id": "001",
          "vehicle_type": "car"
        }
      },
      {
        "title": "vehicle-inspection-002",
        "createVideo": false,
        "objectUrl_0": "s3://my-bucket/vehicle-002/front.jpg",
        "objectUrl_1": "s3://my-bucket/vehicle-002/side.jpg",
        "objectUrl_2": "s3://my-bucket/vehicle-002/rear.jpg",
        "clientMetadata": {
          "inspection_id": "002",
          "vehicle_type": "truck"
        }
      },
      {
        "title": "vehicle-inspection-003",
        "createVideo": false,
        "objectUrl_0": "s3://my-bucket/vehicle-003/front.jpg",
        "objectUrl_1": "s3://my-bucket/vehicle-003/side.jpg",
        "objectUrl_2": "s3://my-bucket/vehicle-003/rear.jpg",
        "clientMetadata": {
          "inspection_id": "003",
          "vehicle_type": "van"
        }
      }
    ],
    "skip_duplicate_urls": true
  }
  ```
</CodeGroup>

### Image Sequences

<CodeGroup>
  ```python Image Sequences at Scale theme={"dark"}
  from pathlib import Path

  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus
  from encord.storage import DataUploadItems

  SSH_PATH = "/path/to/ssh-private-key.txt"
  FOLDER_ID = "00000000-0000-0000-0000-000000000000"
  JSON_FILE = Path("./image-sequences.json")

  user_client = 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)

  upload_job_id = folder.add_private_data_to_folder_start(
      DataUploadItems(file_path=JSON_FILE)
  )

  result = folder.add_private_data_to_folder_get_result(
      upload_job_id,
      timeout_seconds=600,
  )

  if result.status == LongPollingStatus.DONE:
      print("Upload complete.")
      print(result)
  else:
      print("Upload did not complete within the timeout.")
      print(result)

  ```

  ```json image-sequences.json theme={"dark"}
  {
    "image_groups": [
      {
        "title": "drive-sequence-001",
        "createVideo": true,
        "objectUrl_0": "s3://my-bucket/drive-001/frame_0001.jpg",
        "objectUrl_1": "s3://my-bucket/drive-001/frame_0002.jpg",
        "objectUrl_2": "s3://my-bucket/drive-001/frame_0003.jpg",
        "clientMetadata": {
          "sequence_id": "001",
          "scenario": "urban"
        }
      },
      {
        "title": "drive-sequence-002",
        "createVideo": true,
        "objectUrl_0": "s3://my-bucket/drive-001/frame_0001.jpg",
        "objectUrl_1": "s3://my-bucket/drive-001/frame_0002.jpg",
        "objectUrl_2": "s3://my-bucket/drive-001/frame_0003.jpg",
        "clientMetadata": {
          "sequence_id": "002",
          "scenario": "urban"
        }
      },
      {
        "title": "drive-sequence-003",
        "createVideo": true,
        "objectUrl_0": "s3://my-bucket/drive-001/frame_0001.jpg",
        "objectUrl_1": "s3://my-bucket/drive-001/frame_0002.jpg",
        "objectUrl_2": "s3://my-bucket/drive-001/frame_0003.jpg",
        "clientMetadata": {
          "sequence_id": "003",
          "scenario": "urban"
        }
      }
    ],
    "skip_duplicate_urls": true
  }
  ```
</CodeGroup>


# Scene SDK Workflows
Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-scenes



The Scene SDK (`encord.beta.scene`) is the recommended way to register point clouds and synchronized sensor streams in Encord. It lets you build Scenes from point cloud, image, camera, and frame-of-reference streams without writing raw Scene JSON.

Use this guide for the workflow. Use the [Scene SDK reference](/sdk-documentation/sdk-references/beta.scene.builder) for method-level details.

## Build and Upload a Scene

Build the Scene with `SceneBuilder`, then register it into **Files & Folders** with `StorageFolder.upload_scene`.

```python Build and Upload a Scene expandable theme={"dark"}
from uuid import UUID

from encord.beta.scene import SceneBuilder, identity_pose, intrinsics_pinhole
from encord.storage import StorageFolder


def build_scene() -> SceneBuilder:
    scene = SceneBuilder()

    # Anchor the sensor streams to the moving platform.
    ego = scene.add_for_stream("ego")
    ego.add_pose(identity_pose(), timestamp=0)

    # Matching timestamps make the point cloud and image appear together.
    scene.add_pcd_stream("lidar", frame_of_reference=ego).add_pcd(
        uri="s3://my-bucket/scenes/scene-001/lidar/000000.pcd",
        timestamp=0,
    )

    # Inline camera parameters create a camera stream named "front/camera".
    scene.add_image_stream(
        "front",
        width=1920,
        height=1080,
        intrinsics=intrinsics_pinhole(fx=1000, fy=1000, ox=960, oy=540),
        timestamp=0,
        frame_of_reference=ego,
    ).add_image(
        uri="s3://my-bucket/scenes/scene-001/front/000000.jpg",
        timestamp=0,
    )

    return scene


def register_scene(storage_folder: StorageFolder, integration_id: str) -> UUID:
    scene = build_scene()

    # Pass the SceneBuilder itself. upload_scene validates and serializes it internally.
    return storage_folder.upload_scene(
        scene=scene,
        title="scene-001",
        integration_id=integration_id,
        client_metadata={"source": "sample"},
    )
```

`upload_scene` returns the new Scene item UUID. Add that item to a Dataset before creating an annotation Project.

## Add Multi-frame Sensor Streams

Create stream builders once, then append events. Use the same timestamp for events that should appear together in the editor.

```python Multi-frame Scene Streams expandable theme={"dark"}

from encord.beta.scene import Direction, SceneBuilder, intrinsics_pinhole, translation_only


def build_multiframe_scene(frame_count: int = 3) -> SceneBuilder:
    scene = SceneBuilder()
    scene.set_world_convention(x=Direction.FORWARD, y=Direction.LEFT, z=Direction.UP)
    scene.set_camera_convention(x=Direction.RIGHT, y=Direction.DOWN, z=Direction.FORWARD)

    ego = scene.add_for_stream("ego")
    lidar = scene.add_pcd_stream(
        "lidar",
        frame_of_reference=ego,
        pose=translation_only(x=0.0, y=0.0, z=1.8),
    )
    front = scene.add_image_stream(
        "front",
        width=1920,
        height=1080,
        intrinsics=intrinsics_pinhole(fx=1000, fy=1000, ox=960, oy=540),
        timestamp=0,
        frame_of_reference=ego,
        pose=translation_only(x=1.2, y=0.0, z=1.5),
    )

    for frame in range(frame_count):
        ego.add_pose(translation_only(x=frame * 0.5, y=0.0, z=0.0), timestamp=frame)
        lidar.add_pcd(
            uri=f"s3://my-bucket/scenes/scene-001/lidar/{frame:06d}.pcd",
            timestamp=frame,
        )
        front.add_image(
            uri=f"s3://my-bucket/scenes/scene-001/front/{frame:06d}.jpg",
            timestamp=frame,
        )

    return scene
```

Use integer timestamps for frame-indexed data. Use sensor timestamps when streams are sampled at different rates.

## Coordinate Conventions

Set coordinate conventions in the SDK when your data uses known world and camera axes. For example, driving datasets often use a world convention such as forward, left, up and camera axes such as right, down, forward.

Use `SceneBuilder.set_world_convention` and `SceneBuilder.set_camera_convention` with `Direction` values. The world and camera conventions must have matching handedness.

## Scene View Settings

`SceneViewSettings` holds per-Scene rendering settings that the label editor applies when the Scene is opened from the Editor or Explorer view. Unset fields fall through to the annotator's own preferences.

* `point_cloud_colouring` — one of `SceneHeightColouring`, `SceneProvidedColouring`, `SceneSolidColouring`, `SceneImageColouring`, or `SceneSensorColouring`. `SceneHeightColouring` takes `color_height_bounds`, the minimum and maximum heights used for the color gradient.
* `point_radius` — radius used to render point cloud points, from 0 to 100.
* `render_image_outside_base_range` — Render the full image captured by the camera. Useful for wide-angle and fisheye lenses.
* `radius_indicators` — a list of `SceneRadiusIndicator`, each with the `frame_of_reference_id` at its center, a `radius` in scene units, and a hex `color`.
* `radius_filter_enabled` — whether point clouds are filtered to the configured radius indicators.

Assign the settings to `SceneBuilder.settings` before upload, patch a registered Scene with `StorageItem.update(scene_view_settings=...)`, or read them from `SceneReader.view_settings`:

```python Configure Scene View Settings expandable theme={"dark"}
from uuid import UUID

from encord import EncordUserClient
from encord.beta.scene import (
    SceneBuilder,
    SceneHeightColouring,
    SceneProvidedColouring,
    SceneRadiusIndicator,
    SceneReader,
    SceneViewSettings,
    identity_pose,
)
from encord.orm.storage import DataUploadItems
from encord.storage import StorageFolder, StorageItem


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


def register_scene_with_view_settings(
    storage_folder: StorageFolder,
    integration_id: str,
) -> UUID:
    """Create and upload a Scene with initial view settings."""

    scene = SceneBuilder()

    ego = scene.add_for_stream("ego")
    ego.add_pose(identity_pose(), timestamp=0)

    scene.add_pcd_stream(
        "lidar",
        frame_of_reference=ego,
    ).add_pcd(
        uri="s3://my-bucket/scenes/scene-001/lidar/000000.pcd",
        timestamp=0,
    )

    scene.settings = SceneViewSettings(
        point_cloud_colouring=SceneHeightColouring(
            color_height_bounds=(-1.5, 4.0),
        ),
        point_radius=2.0,
        radius_filter_enabled=True,
        radius_indicators=[
            SceneRadiusIndicator(
                frame_of_reference_id="ego",
                radius=3,
                color="#FF8A00",
            ),
            SceneRadiusIndicator(
                frame_of_reference_id="root",
                radius=4,
                color="#3366FF80",
            ),
        ],
    )

    return storage_folder.upload_scene(
        scene=scene,
        title="scene-001",
        integration_id=integration_id,
    )


def update_scene_view_settings(scene_item: StorageItem) -> None:
    """Update the persisted view settings of an existing Scene."""

    reader = SceneReader(scene_item)

    current_settings = reader.view_settings or SceneViewSettings()

    current_settings.point_radius = 5.0

    scene_item.update(
        scene_view_settings=current_settings,
    )


def copy_scene_with_new_view_settings(
    scene_item: StorageItem,
    target_storage_folder: StorageFolder,
    *,
    integration_id: str,
    title: str,
) -> UUID:
    """Copy a Scene with different view settings."""

    reader = SceneReader(scene_item)

    new_settings = reader.view_settings or SceneViewSettings()

    new_settings.point_cloud_colouring = SceneProvidedColouring(
        display_point_intensity=False,
        srgb_colors=True,
    )

    reader.view_settings = new_settings

    # to_upload_payload() includes the Scene's view settings.
    upload_payload = reader.to_upload_payload(title=title)

    return target_storage_folder.add_private_data_to_folder_start(
        integration_id=integration_id,
        private_files=DataUploadItems(
            scenes=[upload_payload],
        ),
    )


# --- Connect to Encord ---

user_client: EncordUserClient = (
    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",
    )
)

folder = user_client.get_storage_folder(FOLDER_ID)
target_folder = user_client.get_storage_folder(TARGET_FOLDER_ID)


# --- Create a Scene with view settings ---

scene_uuid = register_scene_with_view_settings(
    folder,
    INTEGRATION_ID,
)

scene_item = user_client.get_storage_item(scene_uuid)


# --- Read the Scene's view settings ---

reader = SceneReader(scene_item)
print(f"Initial view settings: {reader.view_settings}")


# --- Update the stored Scene's view settings ---

update_scene_view_settings(scene_item)

reader = SceneReader(scene_item)
print(f"Updated view settings: {reader.view_settings}")


# --- Copy the Scene with different view settings ---

copy_job_uuid = copy_scene_with_new_view_settings(
    scene_item,
    target_folder,
    integration_id=INTEGRATION_ID,
    title="scene-001-copy",
)

print(f"Started copy job with UUID: {copy_job_uuid}")
```

`frame_of_reference_id` must be `"root"` for the world frame, or the name of a frame-of-reference stream in the same Scene.

## Read and Copy Registered Scenes

`SceneReader` fetches a registered Scene and returns signed URLs for its constituent files. It can also convert a registered Scene back into a `DataUploadScene` for migration or copying.

```python Read and Copy a Scene expandable theme={"dark"}

from uuid import UUID

from encord.beta.scene import SceneReader
from encord.orm.storage import DataUploadItems, StorageItemType
from encord.storage import StorageFolder, StorageItem


def find_scene(storage_folder: StorageFolder, title: str) -> StorageItem:
    scene_items = storage_folder.list_items(
        search=title,
        item_types=[StorageItemType.SCENE],
        page_size=1,
    )
    scene_item = next(iter(scene_items), None)
    if scene_item is None:
        raise ValueError(f"Scene with title '{title}' not found.")
    return scene_item


def get_lidar_signed_url(scene_item: StorageItem, timestamp: float = 0) -> str:
    scene = SceneReader(scene_item).read()
    lidar = scene.get_stream("lidar", kind="point_cloud")
    return lidar.get_event(timestamp=timestamp).signed_url


def get_image_signed_urls(scene_item: StorageItem, timestamp: float = 0) -> list[tuple[str, str]]:
    scene = SceneReader(scene_item).read()
    return [(stream_id, event.signed_url) for stream_id, event in scene.get_images_at_timestamp(timestamp)]


def copy_scene_to_folder(
    scene_item: StorageItem,
    target_storage_folder: StorageFolder,
    *,
    integration_id: str,
    title: str,
    source_uri_prefix: str,
    target_uri_prefix: str,
) -> UUID:
    payload = SceneReader(scene_item).to_upload_payload(
        title=title,
        uri_mapper=lambda uri: uri.replace(source_uri_prefix, target_uri_prefix),
    )

    return target_storage_folder.add_private_data_to_folder_start(
        integration_id=integration_id,
        private_files=DataUploadItems(scenes=[payload]),
    )
```

Use `find_stream` and `find_event` when a missing stream or timestamp is acceptable. Use `get_stream` and `get_event` when missing data should fail fast.

## Camera Distortion Models

The supported distortion models are defined in [`encord.beta.scene.intrinsics`](/sdk-documentation/sdk-references/beta.scene.intrinsics).

| SDK API                                    | Model type            | Distortion coefficients                        | Use when                                                                   |
| ------------------------------------------ | --------------------- | ---------------------------------------------- | -------------------------------------------------------------------------- |
| `intrinsics_pinhole(...)`                  | `pinhole`             | None                                           | Use for calibrated pinhole cameras with no distortion.                     |
| `intrinsics_radial(...)`                   | `radial`              | `k1`, `k2`, `k3`                               | Use when calibration only supplies radial coefficients.                    |
| `intrinsics_plumb_bob(...)`                | `plumb_bob`           | `k1`, `k2`, `k3`, `t1`, `t2`                   | Use for Brown-Conrady calibration with radial and tangential coefficients. |
| `intrinsics_fisheye(...)`                  | `fisheye`             | `k1`, `k2`, `k3`, `k4`                         | Use for fisheye lenses calibrated with four coefficients.                  |
| `intrinsics_rational_polynomial(...)`      | `rational_polynomial` | `k1`, `k2`, `k3`, `k4`, `k5`, `k6`, `t1`, `t2` | Use for OpenCV rational-polynomial calibration.                            |
| `intrinsics_simple(..., model="division")` | `division`            | `k`                                            | Use for one-parameter division-model calibration.                          |
| `intrinsics_simple(..., model="ucm")`      | `ucm`                 | `xi`, `k1`, `k2`, `k3`                         | Use for unified camera model calibration.                                  |
| `intrinsics_cylindrical(...)`              | `cylindrical`         | None                                           | Use for cylindrical camera projections.                                    |

```python Camera Distortion Models expandable theme={"dark"}

from encord.beta.scene import (
    SimpleIntrinsics,
    intrinsics_cylindrical,
    intrinsics_fisheye,
    intrinsics_pinhole,
    intrinsics_plumb_bob,
    intrinsics_radial,
    intrinsics_rational_polynomial,
    intrinsics_simple,
)


def build_distortion_model_examples() -> dict[str, SimpleIntrinsics]:
    return {
        "pinhole": intrinsics_pinhole(fx=1000, fy=1000, ox=960, oy=540),
        "radial": intrinsics_radial(fx=1000, fy=1000, ox=960, oy=540, k1=0.1, k2=-0.01, k3=0.001),
        "plumb_bob": intrinsics_plumb_bob(
            fx=1000,
            fy=1000,
            ox=960,
            oy=540,
            k1=0.1,
            k2=-0.01,
            k3=0.001,
            t1=0.0001,
            t2=-0.0001,
        ),
        "fisheye": intrinsics_fisheye(
            fx=1000,
            fy=1000,
            ox=960,
            oy=540,
            k1=0.1,
            k2=-0.01,
            k3=0.001,
            k4=-0.0001,
        ),
        "rational_polynomial": intrinsics_rational_polynomial(
            fx=1000,
            fy=1000,
            ox=960,
            oy=540,
            k1=0.1,
            k2=-0.01,
            k3=0.001,
            k4=-0.0001,
            k5=0.00001,
            k6=-0.000001,
            t1=0.0001,
            t2=-0.0001,
        ),
        "division": intrinsics_simple(fx=1000, fy=1000, ox=960, oy=540, model="division", k=0.01),
        "ucm": intrinsics_simple(fx=1000, fy=1000, ox=960, oy=540, model="ucm", xi=0.5, k1=0.1, k2=0, k3=0),
        "cylindrical": intrinsics_cylindrical(fx=1000, fy=1000, ox=960, oy=540),
    }
```

For most workflows, use `intrinsics_pinhole` or a dedicated distortion constructor. Use `intrinsics_advanced` only when you already have full calibration matrices and need to supply them directly.

## Validation Checklist

Before handing Scenes to annotators:

* Confirm every point cloud and image URI is accessible by the integration used for registration.
* Keep stream names stable and descriptive, such as `lidar`, `front`, `rear`, or `ego`.
* Use integer timestamps for frame-indexed data unless you need sensor-time alignment.
* Confirm every `SceneRadiusIndicator` names `"root"` or a frame-of-reference stream the Scene defines. Upload fails otherwise.
* Open at least one registered Scene in the editor to verify orientation, calibration, and frame navigation.

<Card title="Create and Register Scenes" icon="cube" href="/platform-documentation/Curate/add-files/add-pcd-data">
  Learn the Scene data model and registration choices.
</Card>


# Upload & Register Data
Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-upload-data



## Register Cloud Data

### Using a JSON File (Recommended)

The following scripts initiate uploads from your cloud storage to a specified folder in Encord using a [properly formatted JSON upload file](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format). It works for all file types.

<Tip>If `Upload is still in progress, try again later!` is returned, use the script to check the upload status to see whether the upload has finished. </Tip>

Ensure that you:

* Replace \<private\_key\_path> with the path to your private key.
* Replace \<integration\_title> with the title of the integration you want to use.
* Replace \<folder\_name> with the folder name. The scripts assume that the specified folder name is unique.
* Replace `path/to/json/file.json` with the path to a [JSON file specifying which cloud storage files should be uploaded](/platform-documentation/Curate/add-files/index-register-cloud-data#json-format).
* If creating a new folder, replace `A folder to store my files` with a meaningful description for your folder.
* If creating a new folder, replace `"my": "folder_metadata"` with any metadata you want to add to the folder.

<CodeGroup>
  ```python Existing folder theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus
  from encord.storage import FoldersSortBy

  # Instantiate user client. Replace \<private_key_path> with the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
      )

  # Specify the integration you want to use by replacing <integration_title> with the integration title
  integrations = user_client.get_cloud_integrations()
  integration_idx = [i.title for i in integrations].index("<integration_title>")
  integration = integrations[integration_idx].id

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Initiate cloud data registration to the storage folder. Replace path/to/json/file.json with the path to your JSON file
      upload_job_id = storage_folder.add_private_data_to_folder_start(
          integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
      )

      # timeout_seconds determines how long the code waits after initiating upload before checking the upload status
      res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
      print(f"Execution result: {res}")

      if res.status == LongPollingStatus.PENDING:
          print("Upload is still in progress, try again later!")
      elif res.status == LongPollingStatus.DONE:
          print("Upload completed")
          if res.unit_errors:
              print("The following URLs failed to upload:")
              for e in res.unit_errors:
                  print(e.object_urls)
      else:
          print(f"Upload failed: {res.errors}")
  else:
      print("Folder not found")
  ```

  ```python New folder theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus

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

  # Specify the integration you want to use by replacing <integration_title> with the integration title
  integrations = user_client.get_cloud_integrations()
  integration_idx = [i.title for i in integrations].index("<integration_title>")
  integration = integrations[integration_idx].id

  # Create a storage 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)

  # Initiate cloud data registration to the storage folder. Replace path/to/json/file.json with the path to your JSON file
  upload_job_id = storage_folder.add_private_data_to_folder_start(
  integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
      )

  # timeout_seconds determines how long the code waits after initiating upload until continuing and checking upload status
  res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
  print(f"Execution result: {res}")

  if res.status == LongPollingStatus.PENDING:
      print("Upload is still in progress, try again later!")
  elif res.status == LongPollingStatus.DONE:
      print("Upload completed")
      if res.unit_errors:
          print("The following URLs failed to upload:")
          for e in res.unit_errors:
              print(e.object_urls)
  else:
      print(f"Upload failed: {res.errors}")
  ```

  ```Example Output theme={"dark"}
  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.
  ```
</CodeGroup>

<Tip>
  To [update client metadata](/platform-documentation/Curate/add-files/index-register-cloud-data#update-client-metadata), include the `"upsert_metadata": true` flag in the upload JSON file. It can only be used in conjunction with `"skip_duplicate_urls": true`.
</Tip>

**Use the following script to check the status of your private cloud registration.**

<Tip>If `Upload is still in progress, try again later!` is returned, run the script again to check the status at a later time. </Tip>

Ensure that you:

* Replace `<upload_job_id>` with the `upload_job_id` shown in the output of the script used to start the upload. In the example output of the script provided, the `upload_job_id` = `c4026edb-4fw2-40a0-8f05-a1af7f465727`.
* Replace `<private_key_path>` with the path to your private key.
* Replace `<folder_name>` with the folder name. The scripts assume that the specified folder name is unique.

<CodeGroup>
  ```python Check Status theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.dataset import LongPollingStatus

  upload_job_id = <upload_job_id>

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

  # Define search parameters
  folder_name_to_find = "<folder_name>"
  search_result = user_client.find_storage_folders(
      search=folder_name_to_find,
      dataset_synced=None,
      order=FoldersSortBy.NAME,
      desc=False,
      page_size=1000
  )

  # Fetch the folder assuming it's the first one in the search result
  storage_folder = next(search_result, None)
  if folder is None:
      print(f"No folder found with name {folder_name_to_find}")

  # Check upload status
  res = storage_folder.add_private_data_to_dataset_get_result(upload_job_id, timeout_seconds=5)
  print(f"Execution result: {res}")

  if res.status == LongPollingStatus.PENDING:
      print("Upload is still in progress, try again later!")
  elif res.status == LongPollingStatus.DONE:
      print("Upload completed")
      if res.unit_errors:
          print("The following URLs failed to upload:")
          for e in res.unit_errors:
              print(e.object_urls)
  else:
      print(f"Upload failed: {res.errors}")
  ```
</CodeGroup>

***

## Register Cloud Data Without a JSON File

Instead of using a JSON file to specify cloud files and URLs, you can use `DataUploadItems`. This method is recommended for cloud data registrations in the specific use cases listed below.

### Increased Image Group File Registration

You can increase the speed at which Image Groups are registered to Encord by including `imageMetadata` for each image belonging to the image group. For this you must use the following method of importing images and creating Image Groups.

<Warning>
  When the `audioMetadata`, `imageMetadata`, or `videoMetadata` flags are present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. **It is crucial that the metadata you provide is accurate**.
</Warning>

Ensure that you:

* Replace `<path_to_private_key>` with your private key path
* Enter the URLs of images you want to import and batch as an image group.
* Provide the `imageMetadata` for your files by replacing the example values.
* Enter a title and an optional description for your image group.
* Specify the name of the target folder to store the image group.
* Replace `<integration_id>` with the id of the integration you want to use for the data registration.

```python theme={"dark"}
from encord.orm.storage import DataUploadImageGroup, DataUploadImageGroupImage
from encord.orm.storage import CustomerProvidedImageMetadata
from encord import EncordUserClient
from encord.storage import DataUploadItems
from encord.orm.dataset import LongPollingStatus

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<path_to_private_key>"
)

# Enter the URLs of images you want to add to the Image Group
private_cloud_urls = [
    "cloud/path/image1.jpg",
    "cloud/path/image2.jpg",
    "cloud/path/image3.jpg",
]

# Define the new image group using DataUploadImageGroup and DataUploadImageGroupImage
image_group = DataUploadImageGroup(
    images=[
        DataUploadImageGroupImage(
            url=private_cloud_url,
            image_metadata=CustomerProvidedImageMetadata(
                mime_type="image/jpeg",  # MIME type of the image
                file_size=100500,       # File size in bytes
                height=768,             # Image height in pixels
                width=1024,             # Image width in pixels
            ),
        )
        for private_cloud_url in private_cloud_urls
    ],
    title="Group from Frames",  # Title for the image group
    description="A group of images created from frame URLs.",  # Optional description
)

# Specify the target folder
folder_name = "Target Folder Name"
storage_folder = next(user_client.find_storage_folders(
    search=folder_name, dataset_synced=None, page_size=1))

# Start the upload job
upload_job_id = storage_folder.add_private_data_to_folder_start(
    integration_id="<integration_id>",
    private_files=DataUploadItems(
        image_groups=[image_group]  # Add the new image group
    ),
    ignore_errors=True
)

# Monitor the upload status
res = storage_folder.add_private_data_to_folder_get_result(upload_job_id)
if res.status == LongPollingStatus.DONE:
    print("Image group registered successfully!")
else:
    print("Error registering image group.")
```

### Create an Image Group from Existing Images

You can create Image Groups from individual images previously added to Encord. If the individual images include `clientMetadata` and are then grouped into an Image Group, this metadata is retained at the frame level within the Image Group.

The following script combines three previously uploaded images in Encord into a single Image Group.

In the following script:

* Replace `<private_key_path>` with your private key path.
* Replace the titles in the `file_names` list with the names of images to be grouped.
* Replace `<folder_name>` with the title for the folder containing the files.
* Provide a title for the image group.
* Replace `<integration_id>` with the ID of the integration being used.
* Add optional `clientMetadata` for the image group.

```python theme={"dark"}
from encord.orm.storage import DataUploadImageGroupFromItems
from typing import List
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus
from encord.storage import StorageItemType, FoldersSortBy, DataUploadItems

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )
            

# Define a list of file names you want to search for
file_names = ["Image1.jpg", "Image2.jpg", "Image3.jpg"]

image_group_title = "My Image Group"

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]
else: 
    print ("Folder name not found")

# Specify the integration you want to use
integration_id = "<integration_id>"

# Loop through each file name in the list and search for it
for file_name in file_names:
    # Search for the specific data unit(s) using the file name
    items = storage_folder.list_items(
        search=file_name,
        is_in_dataset=None,  
        item_types=[StorageItemType.IMAGE],
        order=FoldersSortBy.NAME,
        desc=False,
        get_signed_urls=False,
        page_size=1000  # Expecting possibly multiple results
    )

    image_uuids = []
    # Retrieve the image UUIDs and add them to the list
    for item in items:
        image_uuids.append(item.uuid)

# Initialize the DataUploadImageGroupFromItems object with the necessary data
image_group = DataUploadImageGroupFromItems(
    image_items=image_uuids,           # List of UUIDs for the images to group
    title=image_group_title,            # Title for the group
    client_metadata={"client": "metadata", "description": "Group of 3 images"},
    create_video=False                 # Specify if you want a video to be generated
)

# Start the upload job for the image group
upload_job_id = storage_folder.add_private_data_to_folder_start(
    integration_id=integration_id,
    private_files= DataUploadItems(
        image_groups_from_items=[image_group]  # Add the group as an item
    ),
    ignore_errors=True
)

# Check the status of the upload
res = storage_folder.add_private_data_to_folder_get_result(upload_job_id)
if res.status == LongPollingStatus.DONE:
    print("Image group created successfully!")
else:
    print("There was an issue creating the image group.")
```

***

## Local Data

### Upload Local Data to an Existing Folder

The following scripts add data to a folder that already exists in **Data** > **Files & Folders**.

* Replace `<folder_name>` with the name of the folder you want to add data to.
* For images and videos replace `User/path/to/my/file` with the path to your image or video file.
* For DICOM series replace `User/path/to/dicom/file1` and `User/path/to/dicom/file2` with the paths to the DICOM files you want to create a series from. Add as many file paths as necessary.
* For image groups and image sequences, replace `User/path/to/image/file1` and `User/path/to/image/file2` with the paths to the image files you want to create an image group or image sequence from. Add as many file paths as necessary.

<CodeGroup>
  ```python Image theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Upload an image to the folder. Substitute file path
      file_path = "User/path/to/my/file"
      client_metadata = {"client": "metadata"}
      image_uuid = storage_folder.upload_image(file_path, None, client_metadata=client_metadata)
  else:
      print("Folder not found")
  ```

  ```python Video theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Upload a video to the folder. Substitute file path
      file_path = "User/path/to/my/video"
      client_metadata = {"client": "metadata"}
      video_uuid = storage_folder.upload_video(file_path, None, client_metadata=client_metadata)
  else:
      print("Folder not found")
  ```

  ```python Image Group theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Create an image group and upload it to the folder. Substitute file paths
      file_title = "<file_title>"
      file_paths = ["User/path/to/image/file1", "User/path/to/image/file2"]  # List of paths to image files
      client_metadata = {"client": "metadata"}
      group_uuid = storage_folder.create_image_group(
          file_paths,  
          file_title,
          client_metadata=client_metadata,
      )
  else:
      print("Folder not found")
  ```

  ```python PDF theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Substitute file path to pdf
      file_path = "User/path/to/my/file.pdf"
      client_metadata = {"client": "metadata"}
      image_uuid = storage_folder.upload_pdf(file_path, None, client_metadata=client_metadata)
  else:
      print("Folder not found")
  ```

  ```python Audio theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Substitute file path to audio
      file_path = "User/path/to/my/file.mp3"
      client_metadata = {"client": "metadata"}
      image_uuid = storage_folder.upload_audio(file_path, None, client_metadata=client_metadata)
  else:
      print("Folder not found")
  ```

  ```python Image Sequence theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Create an image sequence and upload it to the folder. Substitute file paths
      file_title = "<file_title>"
      file_paths = ["User/path/to/image/file1", "User/path/to/image/file2"]  # List of paths to image files
      client_metadata = {"client": "metadata"}
      sequence_uuid = storage_folder.create_image_sequence(
          file_paths,  
          file_title,
          client_metadata=client_metadata,
      )
  else:
      print("Folder not found")
  ```

  ```python DICOM Series theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Create a DICOM series and upload it to the folder. Substitute file paths
      file_title = "<file_title>"
      file_paths = ["User/path/to/dicom/file1", "User/path/to/dicom/file2"]  # List of paths to DICOM files
      client_metadata = {"client": "metadata"}
      series_uuid = storage_folder.create_dicom_series(
          file_paths,
          file_title,
          client_metadata=client_metadata,
      )
  else:
      print("Folder not found")
  ```

  ```python NIfTI  theme={"dark"}
  from encord import EncordUserClient
  from encord.storage import FoldersSortBy

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # Upload NIfTI files to the folder. Substitute file path.
      file_title = "<file_title>"
      file_path = "User/path/to/nifti/file1"  # Path to NIfTI files
      client_metadata = {"client": "metadata"}
      series_uuid = storage_folder.upload_nifti(
          file_path,
          file_title,
          client_metadata=client_metadata,
      )
  else:
      print("Folder not found")
  ```
</CodeGroup>

***

### Upload Local Data to a New Folder

The following script creates a new folder in **Data** > **Files & Folders** and uploads image, video, DICOM, image group, or image sequence files to the newly created folder. A new folder is created each time the script is run.

In the following scripts, ensure that you:

* Replace \<private\_key\_path> with the path to your private key.
* Replace \<folder\_name> with the name you want to give your folder. The scripts assume that the specified folder name is unique.
* Replace `A folder to store my files` with a meaningful description for your folder.
* Replace `my: folder_metadata` with any metadata you want to add to the folder. Remove the line if you do not want to add any metadata to the folder.
* For images and videos replace `User/path/to/my/file` with the path to your image or video file.
* For DICOM series replace `User/path/to/dicom/file1` and `User/path/to/dicom/file2` with the paths to the DICOM files you want to create a series from. Add as many file paths as necessary.
* For image groups and image sequences, replace `User/path/to/image/file1` and `User/path/to/image/file2` with the paths to the image files you want to create an image group or image sequence from. Add as many file paths as necessary.

<CodeGroup>
  ```python Image theme={"dark"}
  from encord import EncordUserClient

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Create a storage 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)

  # Upload an image to the folder. Substitute file path
  file_path = "User/path/to/my/file"
  client_metadata = {"client": "metadata"}
  image_uuid = storage_folder.upload_image(file_path, None, client_metadata=client_metadata)
  ```

  ```python Video theme={"dark"}
  from encord import EncordUserClient

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Create a storage 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)

  # Upload a video to the folder. Substitute file path
  file_path = "User/path/to/my/file"
  client_metadata = {"client": "metadata"}
  video_uuid = storage_folder.upload_video(file_path, None, client_metadata=client_metadata)
  ```

  ```python Image group theme={"dark"}
  from encord import EncordUserClient

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Create a storage 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 an image group and upload it to the folder. Substitute file paths
  file_title = "<file_title>"
  file_paths = ["User/path/to/image/file1", "User/path/to/image/file2"] # List of paths to image files
  client_metadata = {"client": "metadata"}
  group_uuid = storage_folder.create_image_group(
          file_paths,  
          file_title,
          client_metadata=client_metadata,
      )
  ```

  ```python Image sequence theme={"dark"}
  from encord import EncordUserClient

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Create a storage 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 an image sequence and upload it to the folder. Substitute file paths
  file_title = "<file_title>"
  file_paths = ["User/path/to/image/file1", "User/path/to/image/file2"]
  client_metadata = {"client": "metadata"}
  sequence_uuid = storage_folder.create_image_group(
          file_paths,  # List of paths to image files
          file_title,
          client_metadata=client_metadata,
      )
  ```

  ```python DICOM series theme={"dark"}
  from encord import EncordUserClient

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
                  ssh_private_key_path="<private_key_path>"
              )

  # Create a storage 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 a DICOM series and upload it to the folder. Substitute file paths
  file_title = "<file_title>"
  file_paths = ["User/path/to/dicom/file1", "User/path/to/dicom/file2"] # List of paths to DICOM files.
  client_metadata = {"client": "metadata"}
  series_uuid = storage_folder.create_dicom_series(
      file_paths
      file_title,
      client_metadata=client_metadata,
  )
  ```
</CodeGroup>

***

## List Data Units in a Folder

Listing the files in a folder can be used to verify that all data unit were successfully uploaded.

* Replace \<private\_key\_path> with the path to your private key.
* Replace \<folder\_name> with the name you want to give your folder. The scripts assume that the specified folder name is unique.

<CodeGroup>
  ```python All files theme={"dark"}
  from encord import EncordUserClient
  from encord.orm.storage import StorageItemType, FoldersSortBy

  # Authentication
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # List all data units
      items = list(storage_folder.list_items())

      # Output the retrieved data units
      for item in items:
          print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")
  else:
      print("Folder not found.")
  ```

  ```python Images theme={"dark"}
  from encord import EncordUserClient
  from encord.orm.storage import StorageItemType, FoldersSortBy

  # Authentication
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # List images
      images = list(storage_folder.list_items(item_types=[StorageItemType.IMAGE]))

      # Output the retrieved images
      for image in images:
          print(f"UUID: {image.uuid}, Name: {image.name}")
  else:
      print("Folder not found.")
  ```

  ```python Videos theme={"dark"}
  from encord import EncordUserClient
  from encord.orm.storage import StorageItemType, FoldersSortBy

  # Authentication
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # List videos
      videos = list(storage_folder.list_items(item_types=[StorageItemType.VIDEO]))

      # Output the retrieved videos
      for video in videos:
          print(f"UUID: {video.uuid}, Name: {video.name}")
  else:
      print("Folder not found.")
  ```

  ```python Image groups theme={"dark"}
  from encord import EncordUserClient
  from encord.orm.storage import StorageItemType, FoldersSortBy

  # Authentication
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # List image groups
      image_groups = list(storage_folder.list_items(item_types=[StorageItemType.IMAGE_GROUP]))

      # Output the retrieved image groups
      for group in image_groups:
          print(f"UUID: {group.uuid}, Name: {group.name}")
  else:
      print("Folder not found.")
  ```

  ```python Image sequences theme={"dark"}
  from encord import EncordUserClient
  from encord.orm.storage import StorageItemType, FoldersSortBy

  # Authentication
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # List image sequences
      image_sequences = list(storage_folder.list_items(item_types=[StorageItemType.IMAGE_SEQUENCE]))

      # Output the retrieved image sequences
      for sequence in image_sequences:
          print(f"UUID: {sequence.uuid}, Name: {sequence.name}")
  else:
      print("Folder not found.")
  ```

  ```python DICOM series theme={"dark"}
  from encord import EncordUserClient
  from encord.orm.storage import StorageItemType, FoldersSortBy

  # Authentication
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Find the storage folder by name
  folder_name = "<folder_name>"  # Replace with your folder's name
  folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

  # Ensure the folder was found
  if folders:
      storage_folder = folders[0]

      # List DICOM series
      dicom_series = list(storage_folder.list_items(item_types=[StorageItemType.DICOM_SERIES]))

      # Output the retrieved DICOM series
      for dicom in dicom_series:
          print(f"UUID: {dicom.uuid}, Name: {dicom.name}")
  else:
      print("Folder not found.")
  ```
</CodeGroup>


# Ontologies Basics
Source: https://docs.encord.com/sdk-documentation/ontologies-sdk/ontologies



Ontologies are top-level entities that can be attached to projects that provide a template structure for labels.

<Tip> For a detailed description about ontologies in the Encord platform go [here](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies).</Tip>

<Note>A Project can only have a single Ontology attached to it, but one Ontology can be attached to multiple Projects.</Note>

Each ontology is identified using a unique `<dataset_hash>` - a unique ID that can be found within a Dataset in the Encord platform, as highlighted below.

<div>
  <img />
</div>

To access the Ontology use the [get\_ontology()](/sdk-documentation/sdk-references/user_client#get_ontology) method, that allows you to work with its structure property.

<CodeGroup>
  ```python theme={"dark"}
  from encord import EncordUserClient

  # Authenticate using the path to your private key (see
  # /sdk-documentation/general-sdk/authentication-sdk for more)
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<ENCORD_SSH_KEY_FILE>"
  )

  ontology = user_client.get_ontology("<ontology_hash>")

  ```

  ```python Output theme={"dark"}

  # The <ontology_hash>
  "505afc20-0658-44ab-9d62-dc8d940d8e11" 

  ```
</CodeGroup>

The structure comes as the `OntologyStructure` class.

<Note>Ontologies cannot be deleted using the SDK or the API. Use the Encord platform to delete an Ontology.</Note>

## View Ontology Structure

Use the following script to view the Ontology structure and all other Ontology attributes.

<CodeGroup>
  ```python View Ontology Structure Template theme={"dark"}
  from encord.user_client import EncordUserClient

  # Define constants
  SSH_PATH = "file-path-to-your-ssh-key"

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )


  ontology = user_client.get_ontology("unique-id-of-your-ontology")

  print(ontology.ontology_hash)
  print(ontology.title)
  print(ontology.description)
  print(ontology.created_at)
  print(ontology.last_edited_at)
  print(ontology.structure)

  ```

  ```python Example theme={"dark"}

  from encord.user_client import EncordUserClient

  # Define constants
  SSH_PATH = "/Users/chris-encord/SSH/sdk-ssh-private-key.txt"

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  ontology = user_client.get_ontology('b2421c7c-6ba6-48c9-93c0-3d3c015ad7b1')

  print(ontology.ontology_hash)
  print(ontology.title)
  print(ontology.description)
  print(ontology.created_at)
  print(ontology.last_edited_at)
  print(ontology.structure)

  ```
</CodeGroup>


# Copy Ontologies
Source: https://docs.encord.com/sdk-documentation/ontologies-sdk/ontologies-copy



Copying an ontology allows you to make changes to the structure without affecting the projects that the original ontology is attached to.

```python theme={"dark"}

from encord import EncordUserClient

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    "<your_private_key>"
)

ontology = user_client.get_ontology("<ontology_hash>")
new_ontology = user_client.create_ontology(
    "copy ontology",
    description="<my ontology description>",
    structure=ontology.structure,
)
```


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



## Ontology SDK Basics

An Ontology, or labeling protocol, defines the concepts, relationships, and representations in your data. Ontologies are essential for creating object and frame labels by defining what is being labeled.

<Tip>Before you can apply [Classifications](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#classifications) to a [Collection](/platform-documentation/Curate/curation-basics#collections) in Encord Active, the [Classifications](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#classifications) have to exist in an Ontology in Encord.</Tip>

Encord supports Classifications with nested attributes up to 7 levels deep using Radio buttons (`RadioAttribute`). Checklists and text fields stop the nesting of attributes.

<CodeGroup>
  ```| Attributes nested 7 levels deep theme={"dark"}

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

  ```

  ```| Attributes nested 3 levels deep theme={"dark"}

   - Classification
      - Radio button
        - Radio button
          - Checklist

  ```

  ```| Attributes nested 4 levels deep theme={"dark"}

   - Classification
      - Radio button
        - Radio button
          - Radio button
            - Text box

  ```
</CodeGroup>

## Annotation Ontologies

**Ontology with Annotation:** Creates an Ontology (title="My test Ontology") with a single Bounding Box Object ("Cute cat") in the structure.

**Workflow Project with Ontology and Annotations:** Creates a Workflow Project ("Cats annotation project") with a dataset ("MY\_CAT\_DATASET") and an Ontology.

<CodeGroup>
  ```python Ontology with Annotation theme={"dark"}

  import logging
  import time
  from tqdm import tqdm
  from encord import EncordUserClient
  from encord.objects import Shape, Object, Option, OntologyStructure
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.attributes import RadioAttribute, ChecklistAttribute


  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
      )


  ontology_structure = OntologyStructure()
  ontology_structure.add_object("Cute Cat", shape=Shape.BOUNDING_BOX)

  cat_ontology = user_client.create_ontology(title="My test Ontology", structure=ontology_structure)

  ```

  ```python Workflow Project with Ontology and Annotations theme={"dark"}

  import logging
  import time
  from tqdm import tqdm
  from encord import EncordUserClient
  from encord.objects import Shape, Object, Option, OntologyStructure
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.attributes import RadioAttribute, ChecklistAttribute

  requests_settings = RequestsSettings(
      max_retries=10,
      read_timeout=1800,
      write_timeout=1800,
  )

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
      )

  # Now let's create a project for a cat dataset and provide annotations
  MY_CAT_DATASET = '614bbb51-333a-48d0-9dc5-1e92873a5a44'

  ONTOLOGY_HASH = 'd274a855-06cb-4f50-afac-eef176841b4c'

  WORKFLOW_HASH = 'd330ff92-c397-4914-b056-ed6453f1af3c'

  project_hash = user_client.create_project("Cats annotation project", ontology_hash=ONTOLOGY_HASH, dataset_hashes=[MY_CAT_DATASET], workflow_template_hash=WORKFLOW_HASH)

  project = user_client.get_project(project_hash=project_hash)

  label_row = project.list_label_rows_v2()[0]
  label_row.initialise_labels()

  # Use the cat_object from the other example, and this is how you find it
  cat_object = project.ontology_structure.get_child_by_title("Cute Cat", type_=Object)

  # Create instance of the object - a particular cat we want to label
  cat_object_instance = cat_object.create_instance()

  # Creating bounding box coordinates for a cat on a specific frame of specific media.
  bounding_box_coordinates = BoundingBoxCoordinates(height=0.8, width=0.8, top_left_x=0.1, top_left_y=0.1)

  # Setting these coordinates on a particular frame.
  # Images have only one frame, so it doesn't need to be specified here
  cat_object_instance.set_for_frames(bounding_box_coordinates)

  # Attaching object instance to a particular label row
  label_row.add_object_instance(cat_object_instance)

  # Uploading created frame
  label_row.save()

  ```
</CodeGroup>

## Skeleton (Primitive) Ontologies

Skeletons let you label complex structures, such as a human pose, as a set of connected points (a "primitive" object). Use `add_skeleton_object` to add a skeleton object and its template to an Ontology in a single call. This method mints the object first and then reuses its `feature_node_hash` on the template, which is what the Label Editor needs to render the skeleton correctly.

<Warning>
  Creating a skeleton object with `add_object` and `add_skeleton_template` separately requires you to manually keep their `feature_node_hash` values in sync. Prefer `add_skeleton_object` unless you specifically need to reproduce an existing structure exactly (for example, matching `uid` or `feature_node_hash` values from an export).
</Warning>

**Skeleton Ontology:** Creates an Ontology (title="My skeleton Ontology") with a single skeleton object ("Strawberries") built from a 3-point "Triangle" template.

<CodeGroup>
  ```python Skeleton Ontology theme={"dark"}
  from encord import EncordUserClient
  from encord.objects import OntologyStructure
  from encord.objects.skeleton_template import SkeletonTemplate
  from encord.orm.skeleton_template import SkeletonTemplateCoordinate


  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path='<file-path-to-ssh-private-key>'
      )

  ontology_structure = OntologyStructure()

  # Define a 3-point skeleton template ("Triangle") and the edges connecting its points
  triangle_template = SkeletonTemplate(
      name="Triangle",
      width=100,
      height=100,
      skeleton={
          "0": SkeletonTemplateCoordinate(x=0.30, y=0.30, name="point_0"),
          "1": SkeletonTemplateCoordinate(x=0.45, y=0.30, name="point_1"),
          "2": SkeletonTemplateCoordinate(x=0.35, y=0.45, name="point_2"),
      },
      skeleton_edges={
          "0": {"1": {"color": "#00000"}},
          "1": {"2": {"color": "#00000"}},
      },
  )

  # Adds the skeleton object and its template as a linked pair, sharing one feature_node_hash
  skeleton_object, skeleton_template = ontology_structure.add_skeleton_object(
      name="Strawberries", skeleton_template=triangle_template
  )

  triangle_ontology = user_client.create_ontology(title="My skeleton Ontology", structure=ontology_structure)

  # Prints the ontology hash
  print(triangle_ontology.ontology_hash)

  ```
</CodeGroup>

## Classification Ontologies

<Info>
  * **Standard Classifications** are applied to individual frames.
  * **Global Classifications** are applied to a whole file.
</Info>

Use the following example as a guide to creating your Ontology with Classifications using the SDK.

**Radio button:** Creates an Ontology with 2 radio button lists.

**Checklist:** Creates an Ontology with 3 options in a checklist.

**Text field:** Creates an Ontology with a single text field.

**Number:** Creates an Ontology with a single numerical input field.

**Nested attributes:** Creates an Ontology with 2 levels of nesting.

<Tabs>
  <Tab title="Standard Classifications">
    <CodeGroup>
      ```python Radio Button theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure
      from encord.objects.attributes import RadioAttribute

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new ontology with Classifications
      ontology_structure = OntologyStructure()

      # Adding a Classification of type radio button
      classification = ontology_structure.add_classification()

      cat_colour = classification.add_attribute(RadioAttribute, "colour", required=True)
      cat_colour.add_option("white")
      cat_colour.add_option("black")

      # Create a new ontology with Classifications
      ontology = user_client.create_ontology("Radio Button Ontology", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")
      ```

      ```python Checklist theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure
      from encord.objects.attributes import ChecklistAttribute

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new ontology with Classifications
      ontology_structure = OntologyStructure()

      # Adding classification of a type checklist
      new_classification = ontology_structure.add_classification()

      new_checklist_attribute = new_classification.add_attribute(ChecklistAttribute, "Location")

      # Adding options for the classification
      new_checklist_attribute.add_option("Here")
      new_checklist_attribute.add_option("There")
      new_checklist_attribute.add_option("Everywhere")

      # Create a new ontology with Classifications
      ontology = user_client.create_ontology("Checklist Ontology", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")
      ```

      ```python Number theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure
      from encord.objects.attributes import NumericAttribute

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new Ontology with Classifications
      ontology_structure = OntologyStructure()

      # Adding a Number Classification
      new_classification = ontology_structure.add_classification()

      score_attribute = new_classification.add_attribute(NumericAttribute, "Score", required=True)

      # Create a new ontology with Classifications
      ontology = user_client.create_ontology(title="Ontology with numeric attributes", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")

      ```

      ```python Text Field theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import Shape, Object, Option, OntologyStructure
      from encord.objects.coordinates import BoundingBoxCoordinates
      from encord.objects.attributes import ChecklistAttribute

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new ontology with Classifications
      ontology_structure = OntologyStructure()

      # Adding a Classification of type text field
      new_classification = ontology_structure.add_classification()

      new_text_attribute = new_classification.add_attribute(TextAttribute, "Describe location")

      # Create a new ontology with Classifications
      ontology = user_client.create_ontology("Text Field Ontology", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")
      ```

      ```python Nested Attributes theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import Option, OntologyStructure, attributes
      from encord.objects.attributes import ChecklistAttribute, RadioAttribute, OntologyNestedElement

      requests_settings = RequestsSettings(
          max_retries=10,
          read_timeout=1800,
          write_timeout=1800,
      )

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new ontology with Classifications
      ontology_structure = OntologyStructure()


      new_classification = ontology_structure.add_classification()
      new_radio_attribute = new_classification.add_attribute(RadioAttribute, "Green Eggs and Ham?")
      yes_option = new_radio_attribute.add_option("Yes")
      no_option = new_radio_attribute.add_option("No")


      # Provides 1st level nested attribute. RadioAttribute allows further nesting (up to 7 levels deep)
      nested_attribute_yes = yes_option.add_nested_attribute(RadioAttribute, "Where?") 
      # <---- and here
      here_yes_option = nested_attribute_yes.add_option("Here")
      there_yes_option = nested_attribute_yes.add_option("There")
      everywhere_yes_option = nested_attribute_yes.add_option("Everywhere")


      nested_attribute_no = no_option.add_nested_attribute(RadioAttribute, "Where?") 
      # <---- and here
      here_no_option = nested_attribute_no.add_option("Here")
      there_no_option = nested_attribute_no.add_option("There")
      everywhere_no_option = nested_attribute_no.add_option("Everywhere")

      # Provides 2nd level nested attribute. ChecklistAttribute and TextAttribute prevent further nesting.
      nested_attribute_yes_here = here_yes_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_yes_here.add_option("In a box")
      house_option = nested_attribute_yes_here.add_option("In a house")
      car_option = nested_attribute_yes_here.add_option("In a car")

      nested_attribute_yes_there = there_yes_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_yes_there.add_option("In a box")
      house_option = nested_attribute_yes_there.add_option("In a house")
      car_option = nested_attribute_yes_there.add_option("In a car")

      nested_attribute_yes_everywhere = everywhere_yes_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_yes_everywhere.add_option("In a box")
      house_option = nested_attribute_yes_everywhere.add_option("In a house")
      car_option = nested_attribute_yes_everywhere.add_option("In a car")


      nested_attribute_no_here = here_no_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_no_here.add_option("In a box")
      house_option = nested_attribute_no_here.add_option("In a house")
      car_option = nested_attribute_no_here.add_option("In a car")

      nested_attribute_no_there = there_no_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_no_there.add_option("In a box")
      house_option = nested_attribute_no_there.add_option("In a house")
      car_option = nested_attribute_no_there.add_option("In a car")

      nested_attribute_no_everywhere = everywhere_no_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_no_everywhere.add_option("In a box")
      house_option = nested_attribute_no_everywhere.add_option("In a house")
      car_option = nested_attribute_no_everywhere.add_option("In a car")

      # Create a new Ontology with Classifications
      ontology = user_client.create_ontology("Nested Attributes", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Global Classifications">
    <CodeGroup>
      ```python Radio Button theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure
      from encord.objects.attributes import RadioAttribute
      from encord.objects.classification import OntologyClassificationLevel

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new ontology with Classifications
      ontology_structure = OntologyStructure()

      # Adding a global Classification of type radio button
      classification = ontology_structure.add_classification(level=OntologyClassificationLevel.GLOBAL)

      cat_colour = classification.add_attribute(RadioAttribute, "colour", required=True)
      cat_colour.add_option("white")
      cat_colour.add_option("black")

      # Create a new ontology with Classifications
      ontology = user_client.create_ontology("Radio Button Ontology", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")
      ```

      ```python Checklist theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure
      from encord.objects.attributes import ChecklistAttribute
      from encord.objects.classification import OntologyClassificationLevel

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new ontology with Classifications
      ontology_structure = OntologyStructure()

      # Adding a global checklist classification
      new_classification = ontology_structure.add_classification(level=OntologyClassificationLevel.GLOBAL)

      new_checklist_attribute = new_classification.add_attribute(ChecklistAttribute, "Location")

      # Adding options for the classification
      new_checklist_attribute.add_option("Here")
      new_checklist_attribute.add_option("There")
      new_checklist_attribute.add_option("Everywhere")

      # Create a new Ontology with global checklist Classification
      ontology = user_client.create_ontology("Checklist Ontology", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")
      ```

      ```python Number theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure
      from encord.objects.attributes import NumericAttribute
      from encord.objects.classification import OntologyClassificationLevel

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new Ontology with Classifications
      ontology_structure = OntologyStructure()

      # Adding a Number Classification
      new_classification = ontology_structure.add_classification(level=OntologyClassificationLevel.GLOBAL)

      score_attribute = new_classification.add_attribute(NumericAttribute, "Score", required=True)

      # Create a new ontology with global number Classification
      ontology = user_client.create_ontology(title="Ontology with numeric attributes", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")

      ```

      ```python Text Field theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import Shape, Object, Option, OntologyStructure
      from encord.objects.coordinates import BoundingBoxCoordinates
      from encord.objects.attributes import ChecklistAttribute
      from encord.objects.classification import OntologyClassificationLevel

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new Ontology with Classifications
      ontology_structure = OntologyStructure()

      # Adding a Classification of type text field
      new_classification = ontology_structure.add_classification(level=OntologyClassificationLevel.GLOBAL)

      new_text_attribute = new_classification.add_attribute(TextAttribute, "Describe location")

      # Create a new Ontology with global text Classification
      ontology = user_client.create_ontology("Text Field Ontology", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")
      ```

      ```python Nested Attributes theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import Option, OntologyStructure, attributes
      from encord.objects.attributes import ChecklistAttribute, RadioAttribute, OntologyNestedElement

      requests_settings = RequestsSettings(
          max_retries=10,
          read_timeout=1800,
          write_timeout=1800,
      )

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path='/Users/encord/.ssh/id_ed25519'
          )

      # Create a new Ontology with global Classification
      ontology_structure = OntologyStructure()

      new_classification = ontology_structure.add_classification(level=OntologyClassificationLevel.GLOBAL)
      new_radio_attribute = new_classification.add_attribute(RadioAttribute, "Green Eggs and Ham?")
      yes_option = new_radio_attribute.add_option("Yes")
      no_option = new_radio_attribute.add_option("No")


      # Provides 1st level nested attribute. RadioAttribute allows further nesting (up to 7 levels deep)
      nested_attribute_yes = yes_option.add_nested_attribute(RadioAttribute, "Where?") 
      # <---- and here
      here_yes_option = nested_attribute_yes.add_option("Here")
      there_yes_option = nested_attribute_yes.add_option("There")
      everywhere_yes_option = nested_attribute_yes.add_option("Everywhere")


      nested_attribute_no = no_option.add_nested_attribute(RadioAttribute, "Where?") 
      # <---- and here
      here_no_option = nested_attribute_no.add_option("Here")
      there_no_option = nested_attribute_no.add_option("There")
      everywhere_no_option = nested_attribute_no.add_option("Everywhere")

      # Provides 2nd level nested attribute. ChecklistAttribute and TextAttribute prevent further nesting.
      nested_attribute_yes_here = here_yes_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_yes_here.add_option("In a box")
      house_option = nested_attribute_yes_here.add_option("In a house")
      car_option = nested_attribute_yes_here.add_option("In a car")

      nested_attribute_yes_there = there_yes_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_yes_there.add_option("In a box")
      house_option = nested_attribute_yes_there.add_option("In a house")
      car_option = nested_attribute_yes_there.add_option("In a car")

      nested_attribute_yes_everywhere = everywhere_yes_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_yes_everywhere.add_option("In a box")
      house_option = nested_attribute_yes_everywhere.add_option("In a house")
      car_option = nested_attribute_yes_everywhere.add_option("In a car")


      nested_attribute_no_here = here_no_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_no_here.add_option("In a box")
      house_option = nested_attribute_no_here.add_option("In a house")
      car_option = nested_attribute_no_here.add_option("In a car")

      nested_attribute_no_there = there_no_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_no_there.add_option("In a box")
      house_option = nested_attribute_no_there.add_option("In a house")
      car_option = nested_attribute_no_there.add_option("In a car")

      nested_attribute_no_everywhere = everywhere_no_option.add_nested_attribute(ChecklistAttribute, "Specific location?")
      box_option = nested_attribute_no_everywhere.add_option("In a box")
      house_option = nested_attribute_no_everywhere.add_option("In a house")
      car_option = nested_attribute_no_everywhere.add_option("In a car")

      # Create a new Ontology with Classifications
      ontology = user_client.create_ontology("Nested Attributes", structure=ontology_structure)
      print(f"created ontology {ontology.ontology_hash}")
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Ontologies with Annotations and Classifications

This example explains how to create an Ontology with annotations and classifications.

Ensure you replace:

* `<file-path-to-ssh-private-key>` with the pull path to your private key.
* `My test Ontology` with the name of your Ontology.
* `Cute Cat` with the name of your Ontology class.
* As well as any other options relevant to your Ontology.

<CodeGroup>
  ```python Ontology with Annotations and Classifications theme={"dark"}
  from encord import EncordUserClient
  from encord.objects import Shape, Object, Option, OntologyStructure
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.attributes import RadioAttribute, ChecklistAttribute


  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path='<file-path-to-ssh-private-key>'
      )


  ontology_structure = OntologyStructure()

  # Adding bounding box annotation
  ontology_structure.add_object("Cute Cat", shape=Shape.BOUNDING_BOX)


  # Adding a Classification of type radio button
  classification = ontology_structure.add_classification()
  cat_colour = classification.add_attribute(RadioAttribute, "colour", required=True)
  cat_colour.add_option("white")
  cat_colour.add_option("black")

  # Adding a Classification of type check box
  classification = ontology_structure.add_classification()
  cat_features = classification.add_attribute(ChecklistAttribute, "features")
  cat_features.add_option("soft")
  cat_features.add_option("fluffy")
  cat_features.add_option("friendly")

  cat_ontology = user_client.create_ontology(title="My test Ontology", structure=ontology_structure)

  ```
</CodeGroup>


# Adding Users to Projects
Source: https://docs.encord.com/sdk-documentation/projects-sdk/projects-and-workflows/sdk-adding-users-projects



Users can be added to an existing Project using their emails. You can specify the role of the users being added using the `ProjectUserRole` enum. `ProjectUserRole` can take the following values:

* ADMIN = 0
* ANNOTATOR = 1
* REVIEWER = 2
* ANNOTATOR\_REVIEWER = 3
* TEAM\_MANAGER = 4

<Tip>
  The Project hash can be found within the URL once a Project has been selected:

  `app.encord.com/projects/view/\<project_hash>/summary` or `app.us.encord.com/projects/view/\<project_hash>/summary`
</Tip>

<Tip>For collaborative teams using our SDK, we recommend creating shared service accounts and creating access keys for those shared accounts. For example, to have several people create Ontologies, datasets, and projects programmatically, create an email account for use with Encord (for example, [encord-admins@mycompany.com](mailto:encord-admins@mycompany.com)) and generate an SSH for that email account.</Tip>

The following script shows how to add two new annotators to the project. Note how all users get assigned the same role.

```python Global theme={"dark"}

# Import dependencies
from encord import EncordUserClient, Project
from encord.utilities.project_user import ProjectUserRole

SSH_PATH = "<private-key-path>"

#Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify the project you'd like to add users to
project = user_client.get_project("<project_hash>")

# Add users by specifying their email addresses, as well as the role these users should have.
added_users = project.add_users(
    ["example1@encord.com", "example2@encord.com"],
    ProjectUserRole.ANNOTATOR,
)

# Print the new users added to the project
print(added_users)

```

```python US theme={"dark"}

# Import dependencies
from encord import EncordUserClient, Project
from encord.utilities.project_user import ProjectUserRole

SSH_PATH = "<private-key-path>"

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

# Specify the project you'd like to add users to
project = user_client.get_project("<project_hash>")

# Add users by specifying their email addresses, as well as the role these users should have.
added_users = project.add_users(
    ["example1@encord.com", "example2@encord.com"],
    ProjectUserRole.ANNOTATOR,
)

# Print the new users added to the project
print(added_users)

```


# Automated Labeling
Source: https://docs.encord.com/sdk-documentation/projects-sdk/projects-and-workflows/sdk-automated-labeling-projects



The Encord SDK allows you to interact with Encord’s automated labeling features. Our library includes sampling, augmentation, transformation and labeling algorithms.

## Object interpolation

The [encord.project.Project](/sdk-documentation/sdk-references/project#project) object interpolator allows you to run interpolation algorithms on project labels (requires a project ontology).

Interpolation is supported for the following annotation types:

1. Bounding box

2. Rotatable bounding box

3. Polygon

4. Polyline

5. Object primitive

6. Keypoint

Use the [encord.project.Project.object\_interpolation()](/sdk-documentation/sdk-references/project#object-interpolation) method to run object interpolation.

Key frames, between which interpolation is run, can be obtained from label rows containing videos. The objects to interpolate between key frames is a list of `<object_hash>` values obtained from the `label_row["labels"]["<frame_number>"]["objects"]` entry in the label row. An object (identified by its \<object\_hash>) is interpolated between the key frames where it is present.

The interpolation algorithm can be run on multiple objects with different ontological objects at the same time (for example, you can run interpolation on bounding box, polygon, and keypoint, using the same function call) on any number of key frames.

<CodeGroup>
  ```python Sample Code theme={"dark"}
  # 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)
  print(interpolation_result)
  ```

  ```Example Output theme={"dark"}
  {
      "frame": {
          "objects": [
              {
                  "objectHash": object_uid,
                  "featureHash": feature_uid (from editor ontology),
                  "polygon": {
                      "0": {
                          "x": x1,
                          "y": y1,
                      },
                      "1": {
                          "x": x2,
                          "y": y2,
                      },
                      "2" {
                          "x": x3,
                          "y": y3,
                      },
                      ...,
                  }
              },
              {
                  ...
              }
          ]
      },
      "frame": {
          ...,
      }
  }
  ```
</CodeGroup>

The interpolation algorithm can also be run from sample frames kept locally, with key\_frames passed in a simple JSON structure (see [doc-strings](/sdk-documentation/sdk-references/project#object-interpolation) for more information).

All that is required is a \<feature\_hash> and object\_hash for each object in your set of key frames.


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



Copying a Project creates another Project with the same Ontology and settings. You also have the option to copy over the same users, datasets and models (which are not copied over by default).

The [copy\_project()](/sdk-documentation/sdk-references/project#copy-project) method takes the following parameters, all of which are optional:

* Copy\_datasets: when set to *True*, the datasets from the original Project will be copied over and new tasks will be created from them.

* Copy\_collaborators: when set to *True*, the collaborators from the original Project will be copied over with their existing roles.

* Copy\_models: when set to *True*, the models and their training data from the original Project will be copied over.

The parameters above are set to *False* by default, which means that they don't need to be included if a given feature shouldn't be copied to the new Project.

The [copy\_project()](/sdk-documentation/sdk-references/project#copy-project) method returns the \<project\_hash> of the new project.

<Warning>If collaborators are not copied, reviewer and label mapping settings are not copied over either.</Warning>

<Tip>The project hash can be found within the URL once a project has been selected:</Tip>

> app.encord.com/projects/view/\<project\_hash>/summary

> app.us.encord.com/projects/view/\<project\_hash>/summary

The sample code below demonstrates how to copy a Project in the most simple way.

<CodeGroup>
  ```python Sample Code Global theme={"dark"}
  # 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 Sample Code US theme={"dark"}
  # 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)

  ```

  ```python Example Output theme={"dark"}
  # the new Project's <project_hash>
  "046550d1-13fe-4052-ac99-e6a2d84f9b72" 
  ```
</CodeGroup>

The sample code below demonstrates how to copy a project in a more advanced way.

<CodeGroup>
  ```python Global theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.project import (
      CopyDatasetAction,
      CopyDatasetOptions,
      CopyLabelsOptions,
      ReviewApprovalState
  )

  #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 to be copied
  project = user_client.get_project("<project_hash>")

  # Copy the project
  project.copy_project(
      new_title="foo",            #specify the new project's title
      new_description="bar",      #specify the new project's description
      copy_collaborators=True,    # specify whether project collaborators should be copied to the new project
      copy_datasets=CopyDatasetOptions(
          action=CopyDatasetAction.CLONE,  # This will also create a new dataset
          dataset_title="baz",    #specify the new dataset's title
          dataset_description="quz", # Specify the new dataset's description
          datasets_to_data_hashes_map={
              "<dataset_hash>": ["<data_hash_1", "<data_hash_2"]
          },
      ),
      copy_labels=CopyLabelsOptions(
          accepted_label_statuses=[ReviewApprovalState.APPROVED],     # Copy over all labels in the 'Approved' state.
          accepted_label_hashes=["<label_hash_1>", "<label_hash_2>"], # Copy over labels with the listed hashes.
      ),
  )

  ```

  ```python US theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.orm.project import (
      CopyDatasetAction,
      CopyDatasetOptions,
      CopyLabelsOptions,
      ReviewApprovalState
  )

  #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 to be copied
  project = user_client.get_project("<project_hash>")

  # Copy the project
  project.copy_project(
      new_title="foo",            #specify the new project's title
      new_description="bar",      #specify the new project's description
      copy_collaborators=True,    # specify whether project collaborators should be copied to the new project
      copy_datasets=CopyDatasetOptions(
          action=CopyDatasetAction.CLONE,  # This will also create a new dataset
          dataset_title="baz",    #specify the new dataset's title
          dataset_description="quz", # Specify the new dataset's description
          datasets_to_data_hashes_map={
              "<dataset_hash>": ["<data_hash_1", "<data_hash_2"]
          },
      ),
      copy_labels=CopyLabelsOptions(
          accepted_label_statuses=[ReviewApprovalState.APPROVED],     # Copy over all labels in the 'Approved' state.
          accepted_label_hashes=["<label_hash_1>", "<label_hash_2>"], # Copy over labels with the listed hashes.
      ),
  )

  ```

  ```python Example output theme={"dark"}
  # the new Project's <project_hash>
  "046550d1-13fe-4052-ac99-e6a2d84f9b72"
  ```
</CodeGroup>


# Project Basics
Source: https://docs.encord.com/sdk-documentation/projects-sdk/projects-and-workflows/sdk-project-basics



## Create Projects

To create a Project using the SDK:

1. [Create a Workflow template in the Encord platform](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#creating-templates).
2. Use the Workflow template ID, highlighted in the screenshot below, as a parameters to the [create\_project()](/sdk-documentation/sdk-references/user_client#create-project) method.

<Tip>To use an existing template when creating a Project, users must have Admin privileges on the template. We recommend creating a copy of the Workflow template before Project creation, to ensure you have Admin privileges. </Tip>

<div>
  <img />
</div>

<Note>Projects cannot be deleted using the SDK or the API. Use the Encord platform to delete Projects. </Note>

<CodeGroup>
  ```python Sample Code theme={"dark"}
  # Import dependencies
  from encord.user_client 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 project. Substitute a project title, and dataset hashes of the datasets you'd like to attach, as well as the has of the template you want to use
  project = user_client.create_project(
      project_title="<project_title>",
      dataset_hashes=["<dataset_hash_1>", "<dataset_hash_2>"],
      workflow_template_hash="<template_hash>"
  )

  # Prints the hash of the project you've just created
  print(project)

  ```

  ```python Example Output theme={"dark"}
  # The <project_hash>
  "046550d1-13fe-4052-ac99-e6a2d84f9b72"  
  ```
</CodeGroup>

## View Project Details

The following example shows how to retrieve a Project’s status. You can access other Project details in a similar way. For a complete list of available methods, refer to our [SDK reference for the project class](/sdk-documentation/sdk-references/project).

In the following script replace `<project_hash>` with the unique ID of your Project.

<Tip>
  The project ID can be found within the URL once a project has been selected:

  > app.encord.com/projects/view/\<project\_hash>/summary

  > app.us.encord.com/projects/view/\<project\_hash>/summary
</Tip>

<CodeGroup>
  ```python Global theme={"dark"}

  # 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>")

  # Get Project details using the "<project_hash>" as an identifier
  project = user_client.get_project("<project_hash>")

  # Get Project status
  project_status = project.status

  # Print Project status
  print (project.status)

  ```

  ```python US theme={"dark"}

  # 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>", domain="https://api.us.encord.com")

  # Get Project details using the "<project_hash>" as an identifier
  project = user_client.get_project("<project_hash>")

  # Get Project status
  project_status = project.status

  # Print Project status
  print (project.status)

  ```
</CodeGroup>

### View Collaborator Session Information

<Warning>
  This endpoint is deprecated and retrieves collaborator timers from the Legacy Performance Dashboards, not the Upgraded Analytics Dashboard.

  If you want to access the new Analytics Dashboards using the API or SDK contact your Encord team.
</Warning>

Use the `list_collaborator_timers()` method on a ‘project’ object to obtain session information for each collaborator that has worked on the project within a specified range of dates.

<CodeGroup>
  ```python Global theme={"dark"}

  import datetime

  from encord import EncordUserClient, Project

  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      "<your_private_key>"
  )
  project: Project = user_client.get_project("<project_hash>")

  for timer in project.list_collaborator_timers(
      after=datetime.datetime.now(datetime.timezone.utc)
      - datetime.timedelta(weeks=1)
  ):
      print(f"Collaborator session: {timer}")
  ```

  ```python US theme={"dark"}

  import datetime

  from encord import EncordUserClient, Project

  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      "<your_private_key>", domain="https://api.us.encord.com"
  )
  project: Project = user_client.get_project("<project_hash>")

  for timer in project.list_collaborator_timers(
      after=datetime.datetime.now(datetime.timezone.utc)
      - datetime.timedelta(weeks=1)
  ):
      print(f"Collaborator session: {timer}")
  ```
</CodeGroup>


# Change Project Status
Source: https://docs.encord.com/sdk-documentation/projects-sdk/projects-and-workflows/sdk-project-status-change-status

Learn how to change the status of a Project using Encord's Python SDK.

You can programmatically change the status of your projects using `ProjectStatus`.

You can change a Project's status to any of the following:

* `NOT_STARTED`
* `IN_PROGRESS`
* `PAUSED`
* `COMPLETED`
* `CANCELLED`
* `ARCHIVED`

```python theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.project import ProjectStatus

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Specify the file path to your access key
PROJECT_ID = "c96d3d2a-eeb0-433e-8298-27513f7e4585" # Specify the unique Project ID for the Project

# Authenticate with 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",
)

project = user_client.get_project(PROJECT_ID)
print(project.status)
project.set_status(ProjectStatus.COMPLETE) # Specify the Project status change you want to make

project = user_client.get_project(PROJECT_ID)
print(project.status)
```


# Verify Where Files are Stored (Project)
Source: https://docs.encord.com/sdk-documentation/projects-sdk/projects-and-workflows/sdk-view-project-files



The following script prints the storage locations of all files in a Project. This includes the cloud storage locations for private cloud data, and Encord Files location for local data in the Project. Knowing where your files are storage helps to cross-verify that all data from a cloud bucket has been added to the Project.

<Note>To learn how to view the storage locations of all files in a Dataset, see our documentation [here](/sdk-documentation/datasets-sdk/sdk-view-dataset-files).</Note>

In the following script, ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<project_hash\>` with the hash of the Project you want to know the storage locations for.

<CodeGroup>
  ```python Sample Code theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  # Instantiate client

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

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

  # Print Storage locations
  for log_line in project.list_label_rows_v2():
      data_list = project.get_data(log_line.data_hash, get_signed_url=True)
      print(data_list)
  ```

  ```python Example Output theme={"dark"}
  ({'title': 'chicken-egg_normalized.mp4', 'file_link': 'https://storage.googleapis.com/cord-ai-platform.appspot.com/cord-videos-prod/iaDJxNNrMuQMtFPcP9oszw2OCHm2/d45a91e5-c5f1-470d-86f7-4c2983bfd8d9.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=firebase-adminsdk-64w1p%40cord-ai-platform.iam.gserviceaccount.com%2F20240215%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20240215T110647Z&X-Goog-Expires=604800&X-Goog-SignedHeaders=host&X-Goog-Signature=3f315152fd19b092fafe39713ec01aea2b71a49dba66536e187bdc0b801c01384872104bd0d043eec79c912f40bc32a1a9275f20272ac550b7737432034d9387073f8053a02b2e02db18c9bf925a42ca253af6e62f6b25fc56d49c662cb3383ffdc75c730bad0c79a8ab0c821d6ec460d7bd6a31e93495ffd16aaa8f56e440d7de90d9561b3b2d6098e1923100feacb10c65d94d44b7c44b0c9e09d730c3702c7f3163826906a147e8e469f9158c6ac6f8f2e14b2d0334875f7051c3fe8c8504827ded116163c9afccee84b33f4f5298f1b47d24edf77d210f61626900cf136bbe7dbf738065e450301ae6ee8c79288b66111e9448771b04f26a4e697cadafb0'}, None)
  ```
</CodeGroup>


# Reference
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-activity-logs



This topic provides a comprehensive reference of all events tracked in the Label Editor, including when they occur and what properties are captured for each event.

## Overview

The Encord Editor tracks user interactions and changes to provide analytics, audit trails, and workflow management capabilities. All events are logged with a consistent base structure and additional properties specific to each action type.

## Base Properties

All editor log events include the following base properties:

| Property          | Type   | Description                                                                                |
| ----------------- | ------ | ------------------------------------------------------------------------------------------ |
| `dataUnitId`      | string | The hash/ID of the data unit being annotated                                               |
| `workflowStageId` | string | UUID of the workflow stage                                                                 |
| `workflowTaskId`  | string | UUID of the workflow task (annotation, review task or empty when in view mode)             |
| `branchName`      | string | The branch name (useful when using consensus workflow)                                     |
| `sessionId`       | string | Unique session identifier for the editor session                                           |
| `action`          | string | The specific action being logged (see event-specific sections)                             |
| `actionCategory`  | string | Category of the action: `"object"`, `"classification"`, `"task"`, `"agent"`, or `"editor"` |
| `timestamp`       | string | Timestamp of when the event occurred                                                       |

***

## Object Actions

Object actions track changes to annotation objects (bounding boxes, polygons, points, etc.).

### Common Object Properties

All object actions include these properties:

| Property             | Type                 | Description                                                                                                                                                            |                                              |
| -------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `objectHash`         | string               | Unique identifier for the object                                                                                                                                       |                                              |
| `featureId`          | string               | Feature hash identifying the ontology class/type                                                                                                                       |                                              |
| `labelName`          | string               | Display name of the label/ontology class                                                                                                                               |                                              |
| `labelRanges`        | `[number, number][]` | Frame ranges where the object exists (empty array for segmentations)                                                                                                   |                                              |
| `objectShape`        | string               | Shape type: `"bounding_box"`, `"rotatable_bounding_box"`, `"polygon"`, `"polyline"`, `"point"`, `"skeleton"`, `"bitmask"`, `"cuboid"`, `"segmentation"`, `"cuboid_2d"` |                                              |
| `objectId`           | number               | Numeric ID of the object                                                                                                                                               |                                              |
| `objectCurrentFrame` | number               | null                                                                                                                                                                   | Current frame index (null for segmentations) |

### CREATE\_OBJECT

**When:** An annotation object is created (drawn) in the editor.

**Additional Properties:**

* `eventInformation.coordinates` (null for audio): Object coordinates (bounding box, polygon points, etc.)

**Example:**

```json theme={"dark"}
{
  "action": "create_object",
  "actionCategory": "object",
  "objectHash": "abc123...",
  "featureId": "feature_hash_xyz",
  "labelName": "Person",
  "objectShape": "bounding_box",
  "eventInformation": {
    "coordinates": { "x": 100, "y": 200, "w": 50, "h": 80 }
  }
}

```

### UPDATE\_OBJECT

**When:** An object is modified (frame range, classifications, or feature type changed).

**Additional Properties:**

* `eventInformation.oldRange` (optional): Previous frame ranges `[number, number][]`
* `eventInformation.newRange` (optional): New frame ranges `[number, number][]`
* `eventInformation.oldClassification` (optional): Previous classification values
* `eventInformation.newClassification` (optional): New classification values
* `eventInformation.oldFeatureHash` (optional): Previous feature hash
* `eventInformation.newFeatureHash` (optional): New feature hash
* `eventInformation.lastEditedBy`: User hash of who made the edit

**Note:** Only changed properties are included. If only coordinates change, see `UPDATE_OBJECT` with `EventInformationObjectEditCoordinates`.

### UPDATE\_OBJECT (Coordinate Changes)

**When:** Only the coordinates/shape of an object are modified (e.g., resizing a bounding box, moving polygon vertices).

**Additional Properties:**

* `eventInformation.oldCoordinates`: Previous coordinate values
* `eventInformation.newCoordinates`: New coordinate values
* `eventInformation.lastEditedBy`: User hash of who made the edit

### DELETE\_OBJECT

**When:** An annotation object is deleted.

**Additional Properties:**

* `eventInformation.classifications` (optional): Classification values that were associated with the object
* `eventInformation.coordinates` (optional): Final coordinates of the deleted object

### APPROVE\_OBJECT

**When:** An object is approved during review.

**Additional Properties:**

* `eventInformation.classifications` (optional): Classification values associated with the object
* `eventInformation.isConsensus`: Boolean indicating if this is part of a consensus review
* `eventInformation.previousAction` (optional): Previous review action (`"APPROVE"`, `"REJECT"`, or `"REOPEN"`)

### REJECT\_OBJECT

**When:** An object is rejected during review.

**Additional Properties:**

* `eventInformation.classifications` (optional): Classification values associated with the object
* `eventInformation.isConsensus`: Boolean indicating if this is part of a consensus review
* `eventInformation.previousAction` (optional): Previous review action

### REVERT\_TO\_PENDING\_OBJECT

**When:** An approved or rejected object is reopened/reverted to pending status.

**Additional Properties:**

* `eventInformation.classifications` (optional): Classification values associated with the object
* `eventInformation.isConsensus`: Boolean indicating if this is part of a consensus review
* `eventInformation.previousAction` (optional): Previous review action (typically `"APPROVE"`)

***

## Classification/Attribute Actions

Classification/attribute actions track changes to frame-level or object-level classifications (attributes).

### Common Classification Properties

All classification actions include these properties:

| Property             | Type                 | Description                                      |
| -------------------- | -------------------- | ------------------------------------------------ |
| `classificationHash` | string               | Unique identifier for the classification         |
| `featureId`          | string               | Feature hash identifying the classification type |
| `labelName`          | string               | Display name of the classification               |
| `labelRanges`        | `[number, number][]` | Frame ranges where the classification applies    |

### CREATE\_ATTRIBUTE

**When:** A classification/attribute is created.

**Additional Properties:**

* `eventInformation.classifications`: Object mapping feature hashes to classification results, including:
  * `featureId`: Feature hash
  * `name`: Display name
  * `value`: Selected value
  * Nested answers (for nested attributes)

**Example:**

```json theme={"dark"}
{
  "action": "create_attribute",
  "actionCategory": "classification",
  "classificationHash": "class_abc123...",
  "featureId": "attr_feature_hash",
  "labelName": "Weather",
  "eventInformation": {
    "classifications": {
      "attr_feature_hash": {
        "featureId": "attr_feature_hash",
        "name": "Weather",
        "value": "Sunny"
      }
    }
  }
}

```

### UPDATE\_ATTRIBUTE

**When:** A classification is modified (frame range or value changed).

**Additional Properties:**

* `eventInformation.oldRange` (optional): Previous frame ranges
* `eventInformation.newRange` (optional): New frame ranges
* `eventInformation.oldValue` (optional): Previous classification values
* `eventInformation.newValue` (optional): New classification values
* `eventInformation.lastEditedBy`: User hash of who made the edit

### DELETE\_ATTRIBUTE

**When:** A classification/attribute is deleted.

**Additional Properties:**

* `eventInformation.classifications`: Classification values that were deleted

### APPROVE\_CLASSIFICATION

**When:** A classification is approved during review.

**Additional Properties:**

* `eventInformation.classifications` (optional): Classification values
* `eventInformation.isConsensus`: Boolean indicating if this is part of a consensus review
* `eventInformation.previousAction` (optional): Previous review action

### REJECT\_CLASSIFICATION

**When:** A classification is rejected during review.

**Additional Properties:**

* `eventInformation.classifications` (optional): Classification values
* `eventInformation.isConsensus`: Boolean indicating if this is part of a consensus review
* `eventInformation.previousAction` (optional): Previous review action

### REVERT\_TO\_PENDING\_CLASSIFICATION

**When:** An approved or rejected classification is reopened/reverted to pending status.

**Additional Properties:**

* `eventInformation.classifications` (optional): Classification values
* `eventInformation.isConsensus`: Boolean indicating if this is part of a consensus review
* `eventInformation.previousAction` (optional): Previous review action

## Task Actions

Task actions track workflow-level operations.

### SKIP\_TASK

**When:** A task is skipped in the workflow.

**Additional Properties:**

* `eventInformation.skipReason`: String reason provided for skipping the task

**Example:**

```json theme={"dark"}
{
  "action": "skip_task",
  "actionCategory": "task",
  "eventInformation": {
    "skipReason": "Poor image quality"
  }
}

```

### SAVE\_TASK

**When:** A task is saved (manually or via autosave).

**Additional Properties:**

* `eventInformation.saveType`: Either `"manual"` or `"autosave"`
* `eventInformation.success`: Boolean indicating if the save operation succeeded

### SUBMIT\_TASK

**When:** A task is submitted for review or completion.

**Additional Properties:**

* `eventInformation.labels`: Array of label identifiers (object/classification hashes) included in the submission

**Example:**

```json theme={"dark"}
{
  "action": "submit_task",
  "actionCategory": "task",
  "eventInformation": {
    "labels": ["obj_hash_1", "obj_hash_2", "class_hash_1"]
  }
}

```

### APPROVE\_TASK

**When:** A task is approved during review.

**Additional Properties:**

For **non-consensus** reviews:

* `eventInformation.approvedLabelHashes`: Array of approved label hashes
* `eventInformation.isConsensus`: `false`

For **consensus** reviews (without determining consensus):

* `eventInformation.approvedLabelHashes`: Array of approved label hashes
* `eventInformation.isConsensus`: `true`
* `eventInformation.isDetermineConsensus`: `false`
* `eventInformation.annotatorsWithApprovedLabels`: Array of `{ email: string, hash: string }` for annotators whose labels were approved

For **consensus** reviews (with determining consensus):

* `eventInformation.approvedLabelHashes`: Array of approved label hashes
* `eventInformation.isConsensus`: `true`
* `eventInformation.isDetermineConsensus`: `true`
* `eventInformation.selectedAnnotators`: Array of `{ email: string, hash: string }` for selected annotators
* `eventInformation.winningSetAnnotator`: `{ email: string, hash: string }` for the annotator whose labels won

### REJECT\_TASK

**When:** A task is rejected during review.

**Additional Properties:**

For **non-consensus** reviews:

* `eventInformation.rejectedLabelHashes`: Array of rejected label hashes
* `eventInformation.approvedLabelHashes`: Array of approved label hashes
* `eventInformation.isConsensus`: `false`

For **consensus** reviews:

* `eventInformation.approvedLabelHashes` (optional): Array of approved label hashes
* `eventInformation.isConsensus`: `true`
* `eventInformation.isDetermineConsensus`: Boolean indicating if consensus determination was involved
* `eventInformation.annotators`: Array of annotator identifiers

## Agent Actions

### RUN\_AGENT

**When:** An automated agent/ML model is executed.

**Additional Properties:**

* `eventInformation.objectHashes`: Array of object hashes that were created or modified by the agent
* `eventInformation.agentUuid`: UUID of the agent that was run
* `eventInformation.agentEndpoint`: API endpoint used for the agent
* `eventInformation.agentTitle`: Display title of the agent
* `eventInformation.agentDescription`: Description of the agent
* `eventInformation.success`: Boolean indicating if the agent run succeeded

**Example:**

```json theme={"dark"}
{
  "action": "run_agent",
  "actionCategory": "agent",
  "eventInformation": {
    "objectHashes": ["obj_1", "obj_2"],
    "agentUuid": "agent-uuid-123",
    "agentEndpoint": "/api/v1/agents/detect",
    "agentTitle": "Object Detection Model",
    "agentDescription": "Detects objects in images",
    "success": true
  }
}

```

## Editor Actions

Editor actions track editor-level state changes and user interactions.

### ENTER\_EDITOR

**When:** A user opens/enters the editor.

**Additional Properties:**

* None (empty `eventInformation: {}`)

### ENTER\_EDIT\_MODE

**When:** The editor enters edit mode (e.g., when starting to draw an annotation).

**Additional Properties:**

* None (empty `eventInformation: {}`)

### EXIT\_EDIT\_MODE

**When:** The editor exits edit mode (e.g., after completing an annotation).

**Additional Properties:**

* None (empty `eventInformation: {}`)

### FORCE\_OVERWRITE

**When:** A user forces an overwrite operation (e.g., overwriting existing labels).

**Additional Properties:**

* None (empty `eventInformation: {}`)

## Event Flow Examples

### Creating an Object

1. **ENTER\_EDITOR** - User opens editor
2. **ENTER\_EDIT\_MODE** - User selects drawing tool
3. **CREATE\_OBJECT** - User draws a bounding box
4. **EXIT\_EDIT\_MODE** - User completes the annotation
5. **SAVE\_TASK** (autosave) - System auto-saves
6. **SUBMIT\_TASK** - User submits the task

### Reviewing Objects

1. **APPROVE\_OBJECT** - Reviewer approves object 1
2. **REJECT\_OBJECT** - Reviewer rejects object 2
3. **APPROVE\_TASK** - Reviewer approves the entire task

### Editing an Object

1. **UPDATE\_OBJECT** (coordinates) - User resizes a bounding box
2. **UPDATE\_OBJECT** (feature) - User changes the object's class/type
3. **UPDATE\_OBJECT** (range) - User extends the object to additional frames

## Notes

* All timestamps are in UTC ISO 8601 format
* Empty UUIDs (`EMPTY_UUID`) are used when workflow information is not available
* Classification values are stored as nested objects for complex attribute structures
* Coordinates are stored in shape-specific formats (bounding boxes, polygons, etc.)
* Frame ranges use inclusive start and end frames: `[startFrame, endFrame]`
* Segmentations do not have frame ranges (empty array) or current frame (null)


# Attaching and Removing Datasets
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-attaching-and-removing-datasets



## Adding Datasets to a Project

To add an existing Dataset to a Project, use the \<dataset\_hash>.

<Note>You need to be an admin of the Datasets that you want to add.</Note>

<CodeGroup>
  ```python Sample code theme={"dark"}

  from encord import EncordUserClient, Project

  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      "<your_private_key>"
  )
  project: Project = user_client.get_project("<project_hash>")

  success: bool = project.add_datasets(
      [
          "<dataset_hash1>",
          "<dataset_hash2>",
          # ...
      ]
  )
  print(success)
  ```

  ```python Example Output theme={"dark"}
  # True or False depending on whether job was successful
  True  
  ```
</CodeGroup>

<Note>[`add_datasets()`](/sdk-documentation/sdk-references/project#add-datasets) throws an error if it is unable to add a dataset to a project. See the doc-string documentation for further details.</Note>

### Removing Datasets from a Project

You can remove existing Datasets from a Project, using the dataset \<dataset\_hash> for every Dataset that needs to be removed. To get those hashes, you can follow the example in [Listing existing Datasets](/sdk-documentation/datasets-sdk/sdk-create-and-view-datasets#list-existing-datasets).

<Note>You need to be an admin of the datasets that you want to add.</Note>

<CodeGroup>
  ```python theme={"dark"}

  from encord import EncordUserClient, Project

  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      "<your_private_key>"
  )
  project: Project = user_client.get_project("<project_hash>")


  success: bool = project.remove_datasets(
      [
          "<dataset_hash1>",
          "<dataset_hash2>",
          # ...
      ]
  )
  print(success)

  ```

  ```python Example output theme={"dark"}
  # True or False depending on whether job was successful
  True
  ```
</CodeGroup>

<Note>[`remove_datasets()`](/sdk-documentation/sdk-references/project#remove-datasets) throws an error if it is unable to remove a dataset from a project. See the doc-string documentation for further details.</Note>


# Convert Manual QA Projects into Workflow Projects
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-convert-manualqa-workflow



The following script converts a legacy Manual QA Project into a [Workflow Project](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects). A `.txt` log file containing all Label Rows that can not be copied is created when the script is run.

<Info>You must have Admin permissions for the Workflow template you want to use in this script. [Create a Workflow template](/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates#creating-templates) in the Encord platform to ensure you have Admin permissions.</Info>

<Note>
  * Project collaborators are not copied. Collaborators must be added to the target Workflow Project manually after it is created using this script.
  * Tasks in the Complete stage of the source Project are copied into the Complete stage of the Workflow Project. Source Project tasks in any stage other than Complete are copied into the Annotate stage of the Workflow Project.
</Note>

In the main function of the following script, ensure that you:

* Replace \<private\_key\_path> with the path to the file containing your private key.
* Replace \<source\_project\_hash> with your source Project's hash.
* Replace \<target\_project\_name> with the name you want to give to your target Workflow Project.
* Replace \<workflow\_template\_hash> with the ID of the Workflow template you want to use for the target Project. To use the default Workflow template the `workflow_template_hash` argument must be omitted.

<Warning>
  To use the default Workflow template the `workflow_template_hash` argument must be omitted.
</Warning>

Optionally you can:

* Adjust the [Bundle](/sdk-documentation/sdk-references/http.bundle#bundle) size. The Bundle size in the following script is set to 100, the maximum bundle size.
* Include the hashes of all objects and classifications you want to copy to the target Project. The default `None` copies all objects and classifications from the source Project.

<CodeGroup>
  ```python Global theme={"dark"}
  # 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()

      all_batches = [
          all_source_label_rows[i : i + bundle_size]
          for i in range(0, len(all_source_label_rows), bundle_size)
      ]
      for source_rows_batch in tqdm(all_batches):
          source_bundle = source_project.create_bundle()
          for label_row_s in source_rows_batch:
              if feature_hashes_to_include:
                  label_row_s.initialise_labels(
                      include_object_feature_hashes=set(feature_hashes_to_include),
                      bundle=source_bundle,
                  )
              else:
                  label_row_s.initialise_labels(
                      bundle=source_bundle,
                  )

          source_bundle.execute()

          target_label_rows = {}
          target_bundle = target_project.create_bundle()
          for label_row_s in source_rows_batch:
              matches = target_project.list_label_rows_v2(
                  data_hashes=[label_row_s.data_hash]
              )
              if len(matches) != 1:
                  logging.info(
                      f"Something went wrong, zero or multiple matches found {matches}"
                  )
                  # Track problematic label rows
                  new_problematic_label_rows.append(label_row_s.data_hash)
                  continue
              label_row_t = matches[0]
              label_row_t.initialise_labels(bundle=target_bundle, overwrite=True)
              target_label_rows[label_row_s.data_hash] = label_row_t
          target_bundle.execute()

          target_bundle = target_project.create_bundle()

          for label_row_s in source_rows_batch:
              label_row_t = target_label_rows[label_row_s.data_hash]
              label_row_s_status = label_row_s.annotation_task_status
              if label_row_s_status == "COMPLETED":
                  label_row_t.workflow_complete()

              for obj in label_row_s.get_object_instances():
                  label_row_t.add_object_instance(obj.copy())

              for cl in label_row_s.get_classification_instances():
                  label_row_t.add_classification_instance(cl.copy())
              label_row_t.save(bundle=target_bundle)
          target_bundle.execute()

      return new_problematic_label_rows

  # Define the main function
  def main(
      keyfile: str,
      source_project_hash: str,
      target_project_name: str,
      workflow_template_hash: str,
      bundle_size: int = 50,
      feature_hashes_to_include: Optional[List[str]] = None,
  ):
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=keyfile
      )
      target_project = create_target_project(
          user_client, source_project_hash, target_project_name, workflow_template_hash
      )
      source_project = user_client.get_project(source_project_hash)

      # Process label rows by bundle
      problematic_label_rows = process_by_bundle(
          source_project, target_project, bundle_size, feature_hashes_to_include
      )

      # Write problematic label rows to a log file
      timestamp = time.strftime("%Y%m%d_%H%M%S")
      sanitized_project_name = target_project_name.replace(" ", "_")
      log_filename = (
          f"problematic_label_rows_log_{sanitized_project_name}_{timestamp}.txt"
      )
      with open(log_filename, "w") as log_file:
          for data_hash in problematic_label_rows:
              log_file.write(f"{data_hash}\n")
      print("Done!")
      print(
          f"Access project on https://app.encord.com/projects/view/{target_project.project_hash}/summary"
      )

  # Run the main function. Insert your parameters here
  if __name__ == "__main__":
      keyfile = "<private_key_path>"
      source_project_hash = "<source_project_hash>"
      target_project_name = "<target_project_name>"
      workflow_template_hash = "<workflow_template_hash> "
      bundle_size = 50
      feature_hashes_to_include = None
      
      main(keyfile, source_project_hash, target_project_name, workflow_template_hash, bundle_size, feature_hashes_to_include)
  ```

  ```python US theme={"dark"}
  # 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()

      all_batches = [
          all_source_label_rows[i : i + bundle_size]
          for i in range(0, len(all_source_label_rows), bundle_size)
      ]
      for source_rows_batch in tqdm(all_batches):
          source_bundle = source_project.create_bundle()
          for label_row_s in source_rows_batch:
              if feature_hashes_to_include:
                  label_row_s.initialise_labels(
                      include_object_feature_hashes=set(feature_hashes_to_include),
                      bundle=source_bundle,
                  )
              else:
                  label_row_s.initialise_labels(
                      bundle=source_bundle,
                  )

          source_bundle.execute()

          target_label_rows = {}
          target_bundle = target_project.create_bundle()
          for label_row_s in source_rows_batch:
              matches = target_project.list_label_rows_v2(
                  data_hashes=[label_row_s.data_hash]
              )
              if len(matches) != 1:
                  logging.info(
                      f"Something went wrong, zero or multiple matches found {matches}"
                  )
                  # Track problematic label rows
                  new_problematic_label_rows.append(label_row_s.data_hash)
                  continue
              label_row_t = matches[0]
              label_row_t.initialise_labels(bundle=target_bundle, overwrite=True)
              target_label_rows[label_row_s.data_hash] = label_row_t
          target_bundle.execute()

          target_bundle = target_project.create_bundle()

          for label_row_s in source_rows_batch:
              label_row_t = target_label_rows[label_row_s.data_hash]
              label_row_s_status = label_row_s.annotation_task_status
              if label_row_s_status == "COMPLETED":
                  label_row_t.workflow_complete()

              for obj in label_row_s.get_object_instances():
                  label_row_t.add_object_instance(obj.copy())

              for cl in label_row_s.get_classification_instances():
                  label_row_t.add_classification_instance(cl.copy())
              label_row_t.save(bundle=target_bundle)
          target_bundle.execute()

      return new_problematic_label_rows

  # Define the main function
  def main(
      keyfile: str,
      source_project_hash: str,
      target_project_name: str,
      workflow_template_hash: str,
      bundle_size: int = 50,
      feature_hashes_to_include: Optional[List[str]] = None,
  ):
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=keyfile
      )
      target_project = create_target_project(
          user_client, source_project_hash, target_project_name, workflow_template_hash
      )
      source_project = user_client.get_project(source_project_hash)

      # Process label rows by bundle
      problematic_label_rows = process_by_bundle(
          source_project, target_project, bundle_size, feature_hashes_to_include
      )

      # Write problematic label rows to a log file
      timestamp = time.strftime("%Y%m%d_%H%M%S")
      sanitized_project_name = target_project_name.replace(" ", "_")
      log_filename = (
          f"problematic_label_rows_log_{sanitized_project_name}_{timestamp}.txt"
      )
      with open(log_filename, "w") as log_file:
          for data_hash in problematic_label_rows:
              log_file.write(f"{data_hash}\n")
      print("Done!")
      print(
          f"Access project on https://app.us.encord.com/projects/view/{target_project.project_hash}/summary"
      )

  # Run the main function. Insert your parameters here
  if __name__ == "__main__":
      keyfile = "<private_key_path>"
      source_project_hash = "<source_project_hash>"
      target_project_name = "<target_project_name>"
      workflow_template_hash = "<workflow_template_hash> "
      bundle_size = 50
      feature_hashes_to_include = None
      
      main(keyfile, source_project_hash, target_project_name, workflow_template_hash, bundle_size, feature_hashes_to_include)
  ```

  ```python Example Output Global theme={"dark"}
  100%|██████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:07<00:00,  7.57s/it]
  Done!
  Access project on https://app.encord.com/projects/view/<target_project_hash>/summary
  ```

  ```python Example Output US theme={"dark"}
  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
  ```
</CodeGroup>


# Converting Ontology Shapes
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-converting-ontology-shapes



## Converting polygons to bitmasks

The following script converts polygon labels from the source project into Bitmask labels in the target project. The conversion applies to images, videos, image groups, and image sequences.

For this conversion to be effective, it is crucial that both the source and target projects are linked to the same dataset. The script is agnostic to which workflow stage the source or target data units are in.

<Note>
  To install the required Python dependencies, run the following command in your terminal:

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

  This script utilizes `Typer`, allowing you to conveniently insert arguments in your terminal rather than directly into the script.
</Note>

To execute the script in your terminal, use the following command:

```
python script-name.py
```

Replace `script-name.py` with the actual name of your script and respond to the prompted questions during execution.

For a non-interactive usage, provide the following parameters:

```
python script-name.py --keyfile "<ssh_key_path>" --source-project-hash "<source_project_hash>" --target-project-hash "<target_project_hash>"
```

Replace the placeholders with the appropriate values:

* `script-name.py` with the name of your script.
* `<ssh_key_path>` with the path to your private access key associated with Encord.
* `<source_project_hash>` with the hash of the source project containing the polygon labels.
* `<target_project_hash>` with the hash of the target project that will contain the bitmask labels.

For example:

```
python convert-polygons.py --keyfile "~/.ssh/id_ed25519" --source-project-hash "aaaaaa-bbbb-cccc-ddd-eeeeeeeeeee" --target-project-hash "ffffffff-0000-1111-222-333333333`
```

<Warning>This script is intended for a one-time operation only. Running it more than once will result in duplicate labels.</Warning>

```python theme={"dark"}
import logging
import time
from pathlib import Path
from typing import cast

import cv2
import numpy as np
import typer
from encord import EncordUserClient, Project
from encord.objects import LabelRowV2, Object, Shape
from encord.objects.coordinates import BitmaskCoordinates, PolygonCoordinates
from tqdm import tqdm, trange
from typing_extensions import Annotated

MAX_NUM_EXECUTION_ATTEMPTS = 10


def try_execute(func, kwargs=None):
    for n in range(MAX_NUM_EXECUTION_ATTEMPTS):
        try:
            if kwargs:
                return func(**kwargs)
            else:
                return func()
        except Exception as e:
            logging.warning(
                f"Handling {e} when executing {func} with args {kwargs}.\n" f" Trying again, attempt number {n + 1}."
            )
            time.sleep(0.5 * MAX_NUM_EXECUTION_ATTEMPTS)  # Linear back-off
    raise Exception("Reached maximum number of execution attempts.")


def initialize_label_rows(project: Project, batch_size: int = 200, include_unlabeled: bool = False) -> list[LabelRowV2]:
    label_rows = [lr for lr in project.list_label_rows_v2() if include_unlabeled or lr.label_hash is not None]
    for start in trange(
        0,
        len(label_rows),
        batch_size,
        desc=f"Initializing label rows [{project.title}]",
    ):
        bundle = project.create_bundle()
        for lr in label_rows[start : start + batch_size]:
            lr.initialise_labels(bundle=bundle)
        try_execute(bundle.execute)
    return label_rows


def populate_ontology_of_target_project(
    client: EncordUserClient, source: Project, target: Project
) -> dict[str, Object]:
    # Update the target ontology with potentially missing items
    source_ontology = source.ontology_structure
    target_ontology = client.get_ontology(target.ontology_hash)

    ontology_lookup: dict[str, Object] = {}
    for obj in source_ontology.objects:
        if obj.shape != Shape.POLYGON:
            continue

        # Find the bitmask object in the target ontology with the same name
        match = None
        for tobj in target_ontology.structure.objects:
            if tobj.shape != Shape.BITMASK or tobj.name != obj.name:
                continue
            match = tobj
            break

        if match is None:
            match = target_ontology.structure.add_object(obj.name, Shape.BITMASK)
        ontology_lookup[obj.name] = match

    target_ontology.save()
    return ontology_lookup


def convert_labels(
    keyfile: Annotated[
        Path,
        typer.Option(
            help="Path to private access key associated with Encord",
            prompt="Where is your key-file stored?",
        ),
    ],
    source_project_hash: Annotated[
        str,
        typer.Option(
            help="Hash of the project from which annotations and classifications will be copied",
            prompt="What's the project hash of the SOURCE project?",
        ),
    ],
    target_project_hash: Annotated[
        str,
        typer.Option(
            help="Hash of the project where the bitmasks will be added",
            prompt="What's the project hash of the TARGET project?",
        ),
    ],
):
    keyfile = keyfile.expanduser().resolve()

    # create a connection
    user_client = EncordUserClient.create_with_ssh_private_key(keyfile.expanduser().read_text())

    # Initialize projects
    target_project = user_client.get_project(target_project_hash)
    source_project = user_client.get_project(source_project_hash)

    # Set up the ontology for the target project if not filled already.
    ontology_lookup = populate_ontology_of_target_project(user_client, source_project, target_project)
    target_project.refetch_ontology()

    # Initialize labels
    source_project_label_rows = initialize_label_rows(source_project)
    target_project_label_rows = initialize_label_rows(
        target_project,
        include_unlabeled=True,
    )

    # Lookup for reading labels from the source project
    source_project_label_rows_by_data_hash = {lr.data_hash: lr for lr in source_project_label_rows}

    bundle = target_project.create_bundle()
    bundle_size = 0

    # Perform the conversion from polygons to bitmasks and upload.
    for target_lr in tqdm(target_project_label_rows, desc="Migrating labels"):
        source_lr = source_project_label_rows_by_data_hash.get(target_lr.data_hash)
        if source_lr is None:
            # No labels in source project for the given data point.
            continue

        should_save = False
        for obj in source_lr.get_object_instances():
            if obj.ontology_item.shape != Shape.POLYGON or obj.object_name not in ontology_lookup:
                continue

            new_instance = ontology_lookup[obj.object_name].create_instance()
            has_annotations = False
            for annotation in obj.get_annotations():
                has_annotations = True

                coords = cast(PolygonCoordinates, annotation.coordinates)
                frame_view = source_lr.get_frame_view(frame=annotation.frame)
                width, height = frame_view.width, frame_view.height

                mask = np.zeros((height, width), dtype=np.uint8)
                np_polygon = np.array([[p.x * width, p.y * height] for p in coords.values]).astype(np.int32)
                cv2.fillPoly(mask, [np_polygon], 1)

                target_coordinates = BitmaskCoordinates(mask.astype(bool))
                new_instance.set_for_frames(coordinates=target_coordinates, frames=annotation.frame)

            if has_annotations:
                should_save = True
                target_lr.add_object_instance(new_instance)

        if should_save:
            bundle_size += 1
            target_lr.save(bundle=bundle)

        if bundle_size >= 200:
            try_execute(bundle.execute)
            bundle = target_project.create_bundle()
            bundle_size = 0

        try_execute(target_lr.save)

    if bundle_size > 0:
        try_execute(bundle.execute)

    print("Done!")


if __name__ == "__main__":
    typer.run(convert_labels)
```

## Converting polygons to bounding boxes

The following script converts polygon labels from the source Project into bounding box labels in the target Project. The conversion applies to images, videos, image groups, and image sequences.

For this conversion to be effective, it's crucial that both the source and target Projects are linked to the same Dataset. The script is agnostic to which Workflow stage the source or target data units are in.

<Note>To install the required Python dependencies, run the following command in your terminal:</Note>

> ```
> python -m pip install tqdm typer encord
> ```
>
> This script utilizes `Typer`, allowing you to conveniently insert arguments in your terminal rather than directly into the script.

To execute the script in your terminal, use the following command:

```
python script-name.py
```

Replace `script-name.py` with the actual name of your script and respond to the prompted questions during execution.

For a non-interactive usage, provide the following parameters:

```
python script-name.py --keyfile "<ssh_key_path>" --source-project-hash "<source_project_hash>" --target-project-hash "<target_project_hash>"
```

Replace the placeholders with the appropriate values:

* `script-name.py` with the name of your script.
* `<ssh_key_path>` with the path to your private access key associated with Encord.
* `<source_project_hash>` with the hash of the source project containing the polygon labels.
* `<target_project_hash>` with the hash of the target project that will contain the bounding boxes labels.

For example:

```
python convert-polygons.py --keyfile "~/.ssh/id_ed25519" --source-project-hash "aaaaaa-bbbb-cccc-ddd-eeeeeeeeeee" --target-project-hash "ffffffff-0000-1111-222-333333333`
```

<Warning>This script is intended for a one-time operation only. Running it more than once will result in duplicate labels.</Warning>

```python theme={"dark"}
import logging
import time
from pathlib import Path
from typing import cast

import typer
from encord import EncordUserClient, Project
from encord.objects import LabelRowV2, Object, Shape
from encord.objects.coordinates import BoundingBoxCoordinates, PolygonCoordinates
from tqdm import tqdm, trange
from typing_extensions import Annotated

MAX_NUM_EXECUTION_ATTEMPTS = 10


def try_execute(func, kwargs=None):
    for n in range(MAX_NUM_EXECUTION_ATTEMPTS):
        try:
            if kwargs:
                return func(**kwargs)
            else:
                return func()
        except Exception as e:
            logging.warning(
                f"Handling {e} when executing {func} with args {kwargs}.\n" f" Trying again, attempt number {n + 1}."
            )
            time.sleep(0.5 * MAX_NUM_EXECUTION_ATTEMPTS)  # Linear backoff
    raise Exception("Reached maximum number of execution attempts.")


def initialize_label_rows(project: Project, batch_size: int = 200, include_unlabeled: bool = False) -> list[LabelRowV2]:
    label_rows = [lr for lr in project.list_label_rows_v2() if include_unlabeled or lr.label_hash is not None]
    for start in trange(
        0,
        len(label_rows),
        batch_size,
        desc=f"Initializing label rows [{project.title}]",
    ):
        bundle = project.create_bundle()
        for lr in label_rows[start : start + batch_size]:
            lr.initialise_labels(bundle=bundle)
        try_execute(bundle.execute)
    return label_rows


def populate_ontology_of_target_project(
    client: EncordUserClient, source: Project, target: Project
) -> dict[str, Object]:
    # Update the target ontology with potentially missing items
    source_ontology = source.ontology_structure
    target_ontology = client.get_ontology(target.ontology_hash)

    ontology_lookup: dict[str, Object] = {}
    for obj in source_ontology.objects:
        if obj.shape != Shape.POLYGON:
            continue

        # Find the bounding box object in the target ontology with the same name
        match = None
        for tobj in target_ontology.structure.objects:
            if tobj.shape != Shape.BOUNDING_BOX or tobj.name != obj.name:
                continue
            match = tobj
            break

        if match is None:
            match = target_ontology.structure.add_object(obj.name, Shape.BOUNDING_BOX)
        ontology_lookup[obj.name] = match

    target_ontology.save()
    return ontology_lookup


def convert_labels(
    keyfile: Annotated[
        Path,
        typer.Option(
            help="Path to private access key associated with Encord",
            prompt="Where is your SSH-key file stored?",
        ),
    ],
    source_project_hash: Annotated[
        str,
        typer.Option(
            help="Hash of the project from which annotations and classifications will be copied",
            prompt="What's the project hash of the SOURCE project?",
        ),
    ],
    target_project_hash: Annotated[
        str,
        typer.Option(
            help="Hash of the project where the bounding boxes will be added",
            prompt="What's the project hash of the TARGET project?",
        ),
    ],
):
    keyfile = keyfile.expanduser().resolve()

    # create a connection
    user_client = EncordUserClient.create_with_ssh_private_key(keyfile.expanduser().read_text())

    # Initialize projects
    target_project = user_client.get_project(target_project_hash)
    source_project = user_client.get_project(source_project_hash)

    # Set up the ontology for the target project if not filled already.
    ontology_lookup = populate_ontology_of_target_project(user_client, source_project, target_project)
    target_project.refetch_ontology()

    # Initialize labels
    source_project_label_rows = initialize_label_rows(source_project)
    target_project_label_rows = initialize_label_rows(
        target_project,
        include_unlabeled=True,
    )

    # Lookup for reading labels from the source project
    source_project_label_rows_by_data_hash = {lr.data_hash: lr for lr in source_project_label_rows}

    bundle = target_project.create_bundle()
    bundle_size = 0

    # Perform the conversion from polygons to bounding boxes and upload.
    for target_lr in tqdm(target_project_label_rows, desc="Migrating labels"):
        source_lr = source_project_label_rows_by_data_hash.get(target_lr.data_hash)
        if source_lr is None:
            # No labels in source project for the given data point.
            continue

        should_save = False
        for obj in source_lr.get_object_instances():
            if obj.ontology_item.shape != Shape.POLYGON or obj.object_name not in ontology_lookup:
                continue

            new_instance = ontology_lookup[obj.object_name].create_instance()
            has_annotations = False
            for annotation in obj.get_annotations():
                has_annotations = True

                coords = cast(PolygonCoordinates, annotation.coordinates)
                xs, ys = zip(*((point.x, point.y) for point in coords.values))

                min_x, max_x = min(xs), max(xs)
                min_y, max_y = min(ys), max(ys)

                target_coordinates = BoundingBoxCoordinates(
                    height=max_y - min_y,
                    width=max_x - min_x,
                    top_left_x=min_x,
                    top_left_y=min_y,
                )
                new_instance.set_for_frames(coordinates=target_coordinates, frames=annotation.frame)

            if has_annotations:
                should_save = True
                target_lr.add_object_instance(new_instance)

        if should_save:
            bundle_size += 1
            target_lr.save(bundle=bundle)

        if bundle_size >= 200:
            try_execute(bundle.execute)
            bundle = target_project.create_bundle()
            bundle_size = 0

        try_execute(target_lr.save)

    if bundle_size > 0:
        try_execute(bundle.execute)

    print("Done!")


if __name__ == "__main__":
    typer.run(convert_labels)
```


# Copy Labels between Projects
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-copy-labels



<Info>To copy labels from one Project to another, both Projects must contain the same data unit. The data unit **must** have the same title in both Projects. If the Projects use different Datasets, make sure the data unit names match exactly.</Info>

Use the following script to copy labels from a source Project to a target Project. Before running the script ensure that you:

* Replace `<private_key_path>` with the path to your private key.
* Replace `<source_project_id>` with the Project ID of your source Project.
* Replace `<target_project_id>` with the Project ID of your target Project.
* Optionally set the `OVERWRITE_STRATEGY`
  * `skip`: Ignores tasks with existing labels.
  * `add`: Adds all labels from the source Project to the target Project for all tasks.
  * `overwrite`: Replaces labels in the target Project if they exist in the same data unit.
* Optionally set the `COPY_METHOD` to specify the basis for copying, `DataHash` or `DataTitle`.

```python label_copy.py theme={"dark"}
import argparse
from enum import Enum
from encord import EncordUserClient
from tqdm import tqdm # Make sure tqdm is installed: pip install tqdm

class CopyMethod(Enum):
    DataHash = 0
    DataTitle = 1

def get_empty_labels_flag(label_row):
    """Checks if a label row has no object or classification instances."""
    return not (
        label_row.get_object_instances()
        or label_row.get_classification_instances()
    )

def copy_labels_to_target(source_label_row, target_label_row):
    """Copies all object and classification instances from source to target label row."""
    # Add object instances
    for obj in source_label_row.get_object_instances():
        target_label_row.add_object_instance(obj.copy())
    
    # Add classification instances
    for cl in source_label_row.get_classification_instances():
        target_label_row.add_classification_instance(cl.copy())
    
    # Save the changes to the target label row
    target_label_row.save()

def main(
    keyfile: str,
    source_project_hash: str,
    target_project_hash: str,
    overwrite_strategy: str,
    copy_method: CopyMethod,
):
    """
    Main function to copy labels between two Encord projects.
    """
    user_client = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=keyfile
    )
    source_project = user_client.get_project(source_project_hash)
    target_project = user_client.get_project(target_project_hash)

    # --- Initial Project and Ontology Checks ---
    if source_project.ontology_hash != target_project.ontology_hash:
        raise Exception("Projects must share the same Ontology.")
    
    answer = input(f"Target project title is '{target_project.title}'. Continue (y/n)? ")
    if answer.lower() != "y":
        raise Exception("Aborting: User cancelled project confirmation.")

    if overwrite_strategy not in ["skip", "add", "overwrite"]:
        raise ValueError(
            f"Invalid overwrite strategy: '{overwrite_strategy}'. "
            f"Possible options are: 'skip', 'add', or 'overwrite'."
        )
    
    # --- Overwrite Confirmation if Applicable ---
    should_overwrite_target_labels = (overwrite_strategy == "overwrite")
    if should_overwrite_target_labels:
        answer = input(
            "WARNING: 'overwrite' will remove all current labels in the target label row. Continue (y/n)? "
        )
        if answer.lower() != "y":
            raise Exception("Aborting: User cancelled overwrite confirmation.")

    # --- Label Copying Logic ---
    print("\nStarting label copy process...")
    for target_label_row in tqdm(target_project.list_label_rows_v2(), desc="Processing Label Rows"):
        source_label_row_match = None
        
        # Find matching label row in source project
        if copy_method == CopyMethod.DataTitle:
            matches = list(source_project.list_label_rows_v2(data_title_eq=target_label_row.data_title))
        else:  # Default to DataHash
            matches = list(source_project.list_label_rows_v2(data_hashes=[target_label_row.data_hash]))

        if len(matches) == 1:
            source_label_row_match = matches[0]
            source_label_row_match.initialise_labels() # Ensure source labels are loaded
        elif len(matches) > 1:
            print(f"  Warning: Multiple matches found for '{target_label_row.data_title}' (method: {copy_method.name}). Skipping this target label row.")
            continue
        else: # len(matches) == 0
            print(f"  Warning: No matching source label row found for '{target_label_row.data_title}' (method: {copy_method.name}). Skipping.")
            continue

        target_label_row.initialise_labels() # Ensure target labels are loaded

        # Apply overwrite strategy
        if should_overwrite_target_labels:
            # Clear target labels before copying
            target_label_row.initialise_labels(
                include_object_feature_hashes=set(),
                include_classification_feature_hashes=set(),
            )
            print(f"  Overwriting labels for: {target_label_row.data_title}")
            copy_labels_to_target(source_label_row_match, target_label_row)
        elif get_empty_labels_flag(target_label_row):
            # Target is empty, so always copy
            print(f"  Copying labels to empty target: {target_label_row.data_title}")
            copy_labels_to_target(source_label_row_match, target_label_row)
        else: # Target has labels and not overwriting
            if overwrite_strategy == "skip":
                print(f"  Skipping target data unit '{target_label_row.data_title}' (already has labels).")
            elif overwrite_strategy == "add":
                # 'Add' implies merging, which the original copy_labels function handles by adding
                # new instances. It doesn't clear existing ones.
                print(f"  Adding labels to existing target: {target_label_row.data_title}")
                copy_labels_to_target(source_label_row_match, target_label_row)
            else:
                # This else block should theoretically not be reached due to initial validation
                raise NotImplementedError(
                    f"Unhandled overwrite strategy: '{overwrite_strategy}' with non-empty target."
                )
    print("\nLabel copy process finished.")


if __name__ == "__main__":
    # --- CONFIGURE YOUR VARIABLES HERE ---
    # Replace with the actual path to your Encord SSH private key
    KEYFILE_PATH = "<private_key_path>" 
    
    # Replace with your source project hash
    SOURCE_PROJECT_HASH = "<source_project_id>" 
    
    # Replace with your target project hash
    TARGET_PROJECT_HASH = "<target_project_id>" 
    
    # Choose your strategy for existing labels in the target project:
    # "skip": Do not copy if target has labels.
    # "add": Merge new labels into existing ones (this is the default behavior if target has labels and not 'skip' or 'overwrite').
    # "overwrite": Clear target labels before copying.
    OVERWRITE_STRATEGY = "add" 
    
    # Choose how to match label rows between projects:
    # CopyMethod.DataHash: Matches by data hash (recommended for exact dataset matches).
    # CopyMethod.DataTitle: Matches by data title (use if data hashes differ but titles are unique).
    COPY_METHOD = CopyMethod.DataHash 
    # --- END CONFIGURATION ---

    main(
        keyfile=KEYFILE_PATH,
        source_project_hash=SOURCE_PROJECT_HASH,
        target_project_hash=TARGET_PROJECT_HASH,
        overwrite_strategy=OVERWRITE_STRATEGY,
        copy_method=COPY_METHOD
    )
```


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



Editor logs serve as a comprehensive record of actions performed within the Encord platform's Label Editor.

## View Editor Logs

The following method is available on the Project class to retrieve Editor Logs. `start_time` and `end_time` are required parameters, while the rest are optional filters.

[/sdk-documentation/projects-sdk/sdk-activity-logs#object-actions](/sdk-documentation/projects-sdk/sdk-activity-logs#object-actions)

```python theme={"dark"}
def get_editor_logs(
        start_time: datetime.datetime,
        end_time: datetime.datetime,
        action: Optional[str] = None,
        actor_user_email: Optional[str] = None,
        workflow_stage_id: Optional[UUID] = None,
        data_unit_id: Optional[UUID] = None) -> Iterator[EditorLog]
```

Use the following script to view Editor Logs for a specific project and data unit.

```python theme={"dark"}
import datetime
from encord import EncordUserClient

SSH_PATH = "<your_private_key>"
PROJECT_ID = "<project_id>"
DATA_UNIT_ID = "<data_unit_id>"

# Authenticate
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    domain="https://api.encord.com",
)

# Get the project
project = user_client.get_project(PROJECT_ID)

# Define time range for logs
start_time = datetime.datetime.now() - datetime.timedelta(days=29)
end_time = datetime.datetime.now()

# Logs can be filtered by "action", "actor_user_email", "workflow_stage_id", "data_unit_id"
logs = project.get_editor_logs(
    start_time=start_time,
    end_time=end_time,
)

# Specific logs can be retrieved by passing additional filters
for log in logs:
    print(log.branch_name)
```

## View Task Actions

Task actions can be retrieved using the following method on the Project class. `after` is a required parameter, while the rest are optional filters.

<Info>
  See the full list of task actions [here](/sdk-documentation/projects-sdk/sdk-activity-logs#task-actions).
</Info>

```python theme={"dark"}
def get_task_actions(
    *,
    after: datetime.datetime,
    before: Optional[datetime.datetime] = None,
    actor_email: Union[str, List[str], None] = None,
    action_type: Union[TaskActionType, List[TaskActionType], None] = None,
    workflow_stage_uuid: Union[UUID, List[UUID], str, List[str], None] = None,
    data_unit_uuid: Union[UUID, List[UUID], str, List[str], None] = None
) -> Iterable[TaskAction]
```

The following script retrieves task actions for a specific Project and data unit, filtering for actions that occurred in the last 7 days.

```python theme={"dark"}
import datetime
from encord import EncordUserClient

SSH_PATH = "<your_private_key>"
PROJECT_ID = "<project_id>"
DATA_UNIT_ID = "<data_unit_id>"

# Authenticate
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    domain="https://api.encord.com",
)

# Get the project
project = user_client.get_project(PROJECT_ID)

# Get task action type and the user that made the action
seven_days_ago = datetime.now() - timedelta(days=7)
for action in project.get_task_actions(after=seven_days_ago):
    print(f"{action.action_type} by {action.actor_email}")
```

## Use Cases

### Get History of a Label

```python theme={"dark"}
import datetime
from encord import EncordUserClient

SSH_PATH = "<your_private_key>"
PROJECT_ID = "<project_id>"
DATA_UNIT_ID = "<data_unit_id>"

# Authenticate
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    domain="https://api.encord.com",
)

# Get the project
project = user_client.get_project(PROJECT_ID)

# Define time range for logs
start_time = datetime.datetime.now() - datetime.timedelta(days=29)
end_time = datetime.datetime.now()

# Logs can be filtered by "action", "actor_user_email", "workflow_stage_id", "data_unit_id"
logs = project.get_editor_logs(
    start_time=start_time,
    end_time=end_time,
)

# Filter log by the name of the label
log_in_branch_a = [
    log for log in logs
    if log.labelName == "Porpoise"
]
```

### Approval and Rejection Rates

The following script prints the approval and rejection rates for users in a Project.

<CodeGroup>
  ```python Reviewers theme={"dark"}
  import datetime
  from collections import defaultdict
  from encord import EncordUserClient
  from encord.analytics import TaskActionType

  SSH_PATH = "<your_private_key>"
  PROJECT_ID = "<project_id>"

  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  # Get the project
  project = user_client.get_project(PROJECT_ID)

  # Define time range
  start_time = datetime.datetime.now() - datetime.timedelta(days=29)

  # Fetch only approve and reject actions
  actions = list(project.get_task_actions(
      after=start_time,
      action_type=[TaskActionType.APPROVE, TaskActionType.REJECT],
  ))

  # --- Overall rates ---
  total = len(actions)
  approvals = [a for a in actions if a.action_type == TaskActionType.APPROVE]
  rejections = [a for a in actions if a.action_type == TaskActionType.REJECT]

  print("=== Overall Review Rates ===")
  if not total:
      print("No actions found.")
  else:
      print(f"Total review actions : {total}")
      print(f"Approvals            : {len(approvals)} ({len(approvals) / total * 100:.1f}%)")
      print(f"Rejections           : {len(rejections)} ({len(rejections) / total * 100:.1f}%)")

  # --- Per-reviewer breakdown ---
  reviewer_stats = defaultdict(lambda: {"approved": 0, "rejected": 0})

  for action in actions:
      email = action.actor_email
      if action.action_type == TaskActionType.APPROVE:
          reviewer_stats[email]["approved"] += 1
      elif action.action_type == TaskActionType.REJECT:
          reviewer_stats[email]["rejected"] += 1

  print("\n=== Per-Reviewer Breakdown ===")
  print(f"{'Reviewer':<35} {'Approved':>10} {'Rejected':>10} {'Approval Rate':>15}")
  print("-" * 72)
  for email, stats in sorted(reviewer_stats.items()):
      total_by_reviewer = stats["approved"] + stats["rejected"]
      rate = stats["approved"] / total_by_reviewer * 100 if total_by_reviewer else 0
      print(f"{email:<35} {stats['approved']:>10} {stats['rejected']:>10} {rate:>14.1f}%")
  ```

  ```python Annotators theme={"dark"}
  import datetime
  from collections import defaultdict
  from encord import EncordUserClient
  from encord.analytics import TaskActionType

  SSH_PATH = "<your_private_key>"
  PROJECT_ID = "<project_id>"

  # Authenticate
  user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  # Get the project
  project = user_client.get_project(PROJECT_ID)

  # Define time range
  start_time = datetime.datetime.now() - datetime.timedelta(days=29)

  # Get task actions
  actions = list(project.get_task_actions(
      after=start_time,
      action_type=[TaskActionType.SUBMIT, TaskActionType.APPROVE, TaskActionType.REJECT],
  ))

  # Group by task, sorted by time
  by_task = defaultdict(list)
  for action in actions:
      by_task[action.task_uuid].append(action)
  for events in by_task.values():
      events.sort(key=lambda a: a.timestamp)

  # For each approve/reject, attribute it to the annotator who last submitted
  annotator_stats = defaultdict(lambda: {"approved": 0, "rejected": 0})

  for events in by_task.values():
      current_annotator = None
      for event in events:
          if event.action_type == TaskActionType.SUBMIT:
              current_annotator = event.actor_email
          elif event.action_type == TaskActionType.APPROVE and current_annotator:
              annotator_stats[current_annotator]["approved"] += 1
          elif event.action_type == TaskActionType.REJECT and current_annotator:
              annotator_stats[current_annotator]["rejected"] += 1

  print("=== Approval & Rejection Rates per Annotator ===")
  if not annotator_stats:
      print("No data found.")
  else:
      print(f"{'Annotator':<35} {'Approved':>10} {'Rejected':>10} {'Total':>8} {'Approval Rate':>15}")
      print("-" * 80)
      for email, stats in sorted(annotator_stats.items()):
          total = stats["approved"] + stats["rejected"]
          rate = stats["approved"] / total * 100 if total else 0
          print(f"{email:<35} {stats['approved']:>10} {stats['rejected']:>10} {total:>8} {rate:>14.1f}%")
  ```
</CodeGroup>

## Migrating from Activity Logs to New Editor Logs

### Overview

Encord introduced a Editor Logs to replace the deprecated Activity Logs. The new logs are more structured, scalable, and aligned with how annotation actions are actually performed in the editor.

Migrating to Editor Logs is not just a rename. Using Editor logs is a shift to a more structured, scalable logging system that better reflects real annotation workflows.

After migration you will benefit from:

* Faster queries
* Cleaner filtering
* More reliable audit trails

If you're currently using the deprecated logs, this content will help you transition smoothly.

**Key Differences**

| Deprecated Activity Logs       | New Editor Logs                       |
| ------------------------------ | ------------------------------------- |
| Flat log structure             | Structured, event-based logs          |
| Limited filtering              | Advanced filtering and querying       |
| Loosely tied to editor actions | Directly reflects editor interactions |
| Less scalable                  | Designed for high-volume workflows    |
| Deprecated endpoint            | Actively maintained API               |

Conceptual Shift

The biggest change is how logs are modeled:

Before: Logs were general activity records (who did what, loosely defined)
Now: Logs are editor events, tightly scoped to annotation actions

Think of the new logs as a timeline of precise annotation events, not just audit entries.

### SDK Migration

**1. Replace Deprecated Log Calls**

Deprecated:

```python theme={"dark"}
project.get_activity_logs()
```

Editor Logs:

```python theme={"dark"}
project.get_editor_logs()
```

**2. Update Filtering Logic**

Deprecated logs often required manual filtering after retrieval.

Deprecated:

```python theme={"dark"}
logs = project.get_activity_logs()

filtered = [
    log for log in logs
    if log["action"] == "LABEL_CREATED"
]
```

Editor Logs:

Benefit: Reduced payload size and faster queries

```python theme={"dark"}
logs = project.get_editor_logs(
    event_types=["LABEL_CREATED"]
)
```

**3. Adjust to New Schema**

The structure of each log entry has changed.

Deprecated:

```json theme={"dark"}
{
  "user": "user@email.com",
  "action": "LABEL_CREATED",
  "timestamp": "...",
  "details": {...}
}
```

Editor Logs:

```json theme={"dark"}
{
  "event_type": "LABEL_CREATED",
  "actor": {
    "email": "user@email.com"
  },
  "created_at": "...",
  "payload": {...}
}
```

**Key Field Changes**

| Deprecated  | New           |
| ----------- | ------------- |
| `action`    | `event_type`  |
| `user`      | `actor.email` |
| `timestamp` | `created_at`  |
| `details`   | `payload`     |

### Common Migration Patterns

#### Pattern 1: Tracking Label Creation

Before:

```python theme={"dark"}
logs = project.get_activity_logs()

label_creations = [
    log for log in logs
    if log["action"] == "LABEL_CREATED"
]
```

After:

```python theme={"dark"}
label_creations = project.get_editor_logs(
    event_types=["LABEL_CREATED"]
)
```

#### Pattern 2: Filtering by User

Before:

```python theme={"dark"}
[user_log for user_log in logs if user_log["user"] == email]
```

After:

```python theme={"dark"}
project.get_editor_logs(
    actor_emails=[email]
)
```

#### Pattern 3: Time-Based Queries

Before:

```python theme={"dark"}
[log for log in logs if log["timestamp"] > start_time]
```

After:

```python theme={"dark"}
project.get_editor_logs(
    created_after=start_time
)
```

### Migration Checklist

* Replace all get\_activity\_logs() calls
* Update filtering to use server-side parameters
* Refactor log parsing to new schema (event\_type, actor, payload)
* Validate downstream systems (analytics, dashboards, exports)
* Remove deprecated logic and fallbacks

### Tips and Tricks

1. Event Granularity is Higher

You may see more logs than before because actions are more finely tracked.

Plan for:

Increased volume
More precise filtering

2. Payload Structure Varies by Event

Different event\_types have different payload schemas.

Recommendation:

```python theme={"dark"}
if log["event_type"] == "LABEL_CREATED":
    handle_label_created(log["payload"])
```

3. Pagination Matters

The new logs are designed for scale.

Always handle pagination:

```python theme={"dark"}
logs = project.get_editor_logs(limit=100, cursor=cursor)
```

4. Backward Compatibility

Deprecated logs will be removed.

Do not rely on:

* Old endpoints
* Old schema fields

### Example Migration

Before:

```python theme={"dark"}
logs = project.get_activity_logs()

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

After:

```python theme={"dark"}
logs = project.get_editor_logs(event_types=["LABEL_CREATED"])

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


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



Use `create_project_from_cvat_start()` to initiate a CVAT project import into Encord.

The import runs asynchronously and returns an import UUID, that is then passed to `create_project_from_cvat_get_result()` to poll for the final import status and retrieve the created project information.

```python title="Method example" theme={"dark"}
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,
)
```

Expected CVAT export structure:

```text theme={"dark"}
<CVAT_EXPORT_DIR>/
├── annotations.xml
└── images/
    ├── image1.jpg
    ├── image2.jpg
    └── ...
```

<Note>
  Your Encord Ontology must match the labels and attributes defined in the CVAT export.
</Note>

<CodeGroup>
  ```python title="Full example" theme={"dark"}
  # 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)}")
  ```

  ```xml title="CVAT export example" theme={"dark"}
  <?xml version="1.0" encoding="utf-8"?>
  <annotations>
    <version>1.1</version>

    <meta>
      <task>
        <id>1002075</id>
        <name>b1</name>
        <size>6</size>

        <labels>
          <label>
            <name>apple</name>
            <type>rectangle</type>

            <attributes>
              <attribute>
                <name>colour</name>
                <input_type>radio</input_type>
                <default_value>red</default_value>

                <values>
                  red
                  green
                  blue
                </values>
              </attribute>
            </attributes>
          </label>

          <label>
            <name>stuff</name>
            <type>any</type>
          </label>
        </labels>
      </task>
    </meta>

    <image
      id="1"
      name="example.jpg"
      width="600"
      height="360"
    >
      <polygon
        label="stuff"
        points="400.36,108.26;375.89,135.51;380.34,164.42"
      />

      <box
        label="stuff"
        xtl="381.46"
        ytl="111.59"
        xbr="419.82"
        ybr="175.54"
      />

      <mask
        label="apple"
        width="220"
        height="244"
      >
        <attribute name="colour">green</attribute>
      </mask>
    </image>
  </annotations>
  ```
</CodeGroup>


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



The following script merges 2 or more Projects into a single target Project. The name of the target Project is "Merged Project", and the description contains the source project hashes.

<Info>The source Projects must to have the same Ontology and different Datasets.</Info>

In the following script, ensure that you:

* Replace \<private\_key\_path> with the file path to your private key.
* Replace \<project\_hash-1> and \<project\_hash-2>  with the hashes of the Projects you want to merge. You can add any number of Project hashes to merge.

<CodeGroup>
  ```python Sample Code Global theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from tqdm import tqdm

  # Instantiate the client. Replace \<private_key_path> with the path to the file containing your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
      )

  # Specify Projects to merge 
  project_hashes_to_merge = ["<project_hash-1>", "<project_hash-2>"] #Include as many Projects as you need

  # Create target Project
  def create_target_project(user_client, project_hashes_to_merge):
      dataset_hashes = set([])
      ontology_hash = ""

      for p_hash in project_hashes_to_merge:
          p = user_client.get_project(p_hash)
          new_dataset_hashes = {x['dataset_hash'] for x in p.datasets}
          if new_dataset_hashes.intersection(dataset_hashes):
              raise Exception(f'Source projects should not share datasets!')
          dataset_hashes.update(new_dataset_hashes)

          if not ontology_hash:
              ontology_hash = p.ontology_hash
          elif ontology_hash != p.ontology_hash:
              raise Exception(f'All projects must share the same ontology but '
                              f'https://app.encord.com/projects/view/{p_hash}/summary. does not!')

      project_hash = user_client.create_project(
          "Merged Project",
          list(dataset_hashes),
          f"Merged Projects: {project_hashes_to_merge}",
          ontology_hash=ontology_hash
      )

      return user_client.get_project(project_hash)

  # Main function
  def main(project_hashes_to_merge):
      target_project = create_target_project(user_client, project_hashes_to_merge)

      for source_p_hash in project_hashes_to_merge:
          print(f'Merging in project {source_p_hash}')
          source_project = user_client.get_project(source_p_hash)
          for lr_s in tqdm(source_project.list_label_rows_v2()):
              matches = target_project.list_label_rows_v2(data_hashes=[lr_s.data_hash])
              if len(matches) != 1:
                  print(f'Something went wrong, zero or multiple matches found {matches}')
                  print(lr_s)
              assert len(matches) == 1
              lr_t = matches[0]
              lr_s.initialise_labels()
              lr_t.initialise_labels()

              for obj in lr_s.get_object_instances():
                  lr_t.add_object_instance(obj.copy())

              for cl in lr_s.get_classification_instances():
                  lr_t.add_classification_instance(cl.copy())
              lr_t.save()
      print('Done!')
      print(f'Access project on https://app.encord.com/projects/view/{target_project.project_hash}/summary')

  # Run the main function
  if __name__ == '__main__':
      main(project_hashes_to_merge)
  ```

  ```python Sample Code US theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from tqdm import tqdm

  # Instantiate the client. Replace \<private_key_path> with the path to the file containing your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
      )

  # Specify Projects to merge 
  project_hashes_to_merge = ["<project_hash-1>", "<project_hash-2>"] #Include as many Projects as you need

  # Create target Project
  def create_target_project(user_client, project_hashes_to_merge):
      dataset_hashes = set([])
      ontology_hash = ""

      for p_hash in project_hashes_to_merge:
          p = user_client.get_project(p_hash)
          new_dataset_hashes = {x['dataset_hash'] for x in p.datasets}
          if new_dataset_hashes.intersection(dataset_hashes):
              raise Exception(f'Source projects should not share datasets!')
          dataset_hashes.update(new_dataset_hashes)

          if not ontology_hash:
              ontology_hash = p.ontology_hash
          elif ontology_hash != p.ontology_hash:
              raise Exception(f'All projects must share the same ontology but '
                              f'https://app.us.encord.com/projects/view/{p_hash}/summary. does not!')

      project_hash = user_client.create_project(
          "Merged Project",
          list(dataset_hashes),
          f"Merged Projects: {project_hashes_to_merge}",
          ontology_hash=ontology_hash
      )

      return user_client.get_project(project_hash)

  # Main function
  def main(project_hashes_to_merge):
      target_project = create_target_project(user_client, project_hashes_to_merge)

      for source_p_hash in project_hashes_to_merge:
          print(f'Merging in project {source_p_hash}')
          source_project = user_client.get_project(source_p_hash)
          for lr_s in tqdm(source_project.list_label_rows_v2()):
              matches = target_project.list_label_rows_v2(data_hashes=[lr_s.data_hash])
              if len(matches) != 1:
                  print(f'Something went wrong, zero or multiple matches found {matches}')
                  print(lr_s)
              assert len(matches) == 1
              lr_t = matches[0]
              lr_s.initialise_labels()
              lr_t.initialise_labels()

              for obj in lr_s.get_object_instances():
                  lr_t.add_object_instance(obj.copy())

              for cl in lr_s.get_classification_instances():
                  lr_t.add_classification_instance(cl.copy())
              lr_t.save()
      print('Done!')
      print(f'Access project on https://app.us.encord.com/projects/view/{target_project.project_hash}/summary')

  # Run the main function
  if __name__ == '__main__':
      main(project_hashes_to_merge)
  ```

  ```python Example Output Global theme={"dark"}
  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
  ```

  ```python Example Output US theme={"dark"}
  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
  ```
</CodeGroup>


# Issues & Comments in Projects
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-projects-issues-comments



You can programmatically create issues/comments on data units using Encord's SDK.

## Create Issues

You can use the SDK to create a file issue, frame issue, or a pinned (coordinate) issue.

<CodeGroup>
  ```python Template theme={"dark"}
  task.issues.add_file_issue("<text-about-issue>", ["<issue-tag-1>", "<issue-tag-2"])
  task.issues.add_frame_issue(<frame-number>, "<text-about-issue>", ["<issue-tag-1>", "<issue-tag-2"])
  task.issues.add_coordinate_issue(<frame-number>, <coordinate-x>, <coordinate-y>, "<text-about-issue>", ["<issue-tag-1>", "<issue-tag-2"])
  ```

  ```python Example theme={"dark"}
  task.issues.add_file_issue("File issue from annotate", ["Label too large", "incorrect object"])
  task.issues.add_frame_issue(3, "Frame issue from annotate", ["label too large", "incorrect object"])
  task.issues.add_coordinate_issue(7, 0.5 ,0.5, "Pinned/Coordinate issue from annotate", [])
  ```
</CodeGroup>

<Warning>
  Issue tags are optional. However, if issue tags are specified while adding an issue using the SDK, the issue tags **MUST** exist in the Project.
</Warning>

## Supported Modalities

Not all modalities support all issue types.

<table>
  <thead>
    <tr>
      <th>Modality</th>
      <th>File</th>
      <th>Frame</th>
      <th>Pinned/Coordinate</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Images</td>
      <td>✅</td>
      <td>❌</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Videos</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Audio files</td>
      <td>✅</td>
      <td>✅</td>
      <td>❌</td>
    </tr>

    <tr>
      <td>Text files</td>
      <td>✅</td>
      <td>❌</td>
      <td>❌</td>
    </tr>

    <tr>
      <td>HTML files</td>
      <td>✅</td>
      <td>❌</td>
      <td>❌</td>
    </tr>

    <tr>
      <td>PDFs</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>DICOM</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>NifTi</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

## Using Issues SDK

The following code provides an example of how you are likely going to use the SDK with Issues/Comments.

**ANNOTATE stage**

1. Issues/comments are added to the specified data units.
2. A label is added to the data unit.
3. The task is submitted for review.

**REVIEW stage**

1. Issues/comments are added to the specified data units.
2. The task is rejected.

```python Issues/Comments Annotate and Review Example theme={"dark"}
# Import dependencies
from encord import EncordUserClient
from encord.workflow import AnnotationStage, ReviewStage
from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
from encord.objects.coordinates import BoundingBoxCoordinates

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
PROJECT_ID = "ef4c2685-512a-4af9-9ac1-443f766c6c80"

# Authentication
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",
)

project = user_client.get_project(PROJECT_ID)
workflow = project.workflow


ANNOTATE_ISSUES = [
    {
        "data_title": "cherries-010.jpg",
        "file_issue": {"text": "Annotate file issue 1", "tags": ["incorrect object", "label too large"]},
        "coordinate_issue": {"frame": 0, "x": 0.5, "y": 0.5, "text": "Annotate coordinate issue 1", "tags": ["incorrect object"]},
    },
    {
        "data_title": "cherries-vid-001.mp4",
        "file_issue": {"text": "Annotate file issue 1", "tags": ["incorrect object", "label too large"]},
        "frame_issue": {"frame": 0, "text": "Annotate frame issue 1", "tags": ["incorrect object"]},
        "coordinate_issue": {"frame": 0, "x": 0.5, "y": 0.5, "text": "Annotate coordinate issue 1", "tags": ["incorrect object", "label too large"]},
    },
]

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"]},
    },
    {
        "data_title": "cherries-ig",
        "file_issue": {"text": "Review file issue 1", "tags": ["incorrect object", "label too large"]},
        "frame_issue": {"frame": 2, "text": "Review frame issue 1", "tags": ["incorrect object", "label too large"]},
        "coordinate_issue": {"frame": 0, "x": 0.3, "y": 0.3, "text": "Review coordinate issue 1", "tags": ["incorrect object", "label too large"]},
    },
    {
        "data_title": "cherries-004.jpg",
        "file_issue": {"text": "Review file issue 1", "tags": ["incorrect object", "label too large"]},
        "coordinate_issue": {"frame": 0, "x": 0.3, "y": 0.3, "text": "Review coordinate issue 1", "tags": ["incorrect object", "label too large"]},
    },
]

# Annotate stage
annotate_stage = workflow.get_stage(name='Annotate 1', type_=AnnotationStage)
for issue in ANNOTATE_ISSUES:
    data_title = issue["data_title"]
    task = next((t for t in annotate_stage.get_tasks() if t.data_title == data_title), None)
    if not task:
        print(f"[Annotate] Task not found for: {data_title}")
        continue

    print(f"Processing Annotate Task: {data_title}")
    task.assign('chris-encord@acme.com')

    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"])

    label_row = project.list_label_rows_v2(data_hashes=[task.data_hash])[0]
    label_row.initialise_labels()
    box_object = label_row.ontology_structure.get_child_by_title("BoundingBox", type_=Object)
    box_instance = box_object.create_instance()
    box_instance.set_for_frames(
        coordinates=BoundingBoxCoordinates(height=0.1, width=0.1, top_left_x=0.5, top_left_y=0.5),
    )
    label_row.add_object_instance(box_instance)
    label_row.save()

    task.submit()

# Review stage
review_stage = workflow.get_stage(name='Review 1', type_=ReviewStage)
for issue in REVIEW_ISSUES:
    data_title = issue["data_title"]
    task = next((t for t in review_stage.get_tasks() if t.data_title == data_title), None)
    if not task:
        print(f"[Review] Task not found for: {data_title}")
        continue

    print(f"Processing Review Task: {data_title}")
    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"])

    for label_review in task.get_label_reviews():
        label_review.reject(comment='Rejected due to issue', issue_tags=ci["tags"])  # Or use any tag set you prefer

    task.reject()
```

## Delete Issues

Use `task.issues.delete()` to delete Issues from your Tasks. You can filter by a number of criteria.

<Warning>
  Your **Service Account** MUST be added to the Project as an **Admin** to delete Issues.
</Warning>

<CodeGroup>
  ```python Delete all Issues in a Stage theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.workflow import AnnotationStage

  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 Project ID

  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",
  )

  project = user_client.get_project(PROJECT_ID)
  annotate_stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

  for task in annotate_stage.get_tasks():
      issues_to_delete = list(task.issues.list())
      task.issues.delete(issues_to_delete)
  ```

  ```python Delete Issues on specific Tasks theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.workflow import AnnotationStage

  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 Project ID
  DATA_TITLE = "frame_001.jpg" # Replace with the name of the data unit you want to filter by

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  project = user_client.get_project(PROJECT_ID)
  annotate_stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

  for task in annotate_stage.get_tasks(data_title=DATA_TITLE):
      issues_to_delete = list(task.issues.list())
      task.issues.delete(issues_to_delete)
  ```

  ```python Delete Issues filter by Issue Tag theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.workflow import AnnotationStage

  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 Project ID
  TAG_NAME = "needs-review" # Replace with the Issue Tag you want to filter by

  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",
  )

  project = user_client.get_project(PROJECT_ID)
  annotate_stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

  for task in annotate_stage.get_tasks():
      issues_to_delete = []
      for issue in task.issues.list():
          if any(tag.name == TAG_NAME for tag in issue.tags):
              issues_to_delete.append(issue)

      task.issues.delete(issues_to_delete)
  ```

  ```python Delete Issue by Issue Author theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.workflow import AnnotationStage

  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 Project ID
  AUTHOR_EMAIL = "annotator-001@example.com" # Replace with the author of the Issue

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  project = user_client.get_project(PROJECT_ID)
  annotate_stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

  for task in annotate_stage.get_tasks():
      issues_to_delete = []
      for issue in task.issues.list():
          if issue.comments and issue.comments[0].author_email == AUTHOR_EMAIL:
              issues_to_delete.append(issue)

      task.issues.delete(issues_to_delete)
  ```
</CodeGroup>


# Timers in Projects
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-projects-timers



You can programmatically use timers to view the time spent on Projects, Stages, Tasks, Users and more.

<CodeGroup>
  ```python Timers - All Data theme={"dark"}

  from datetime import datetime

  from encord import EncordUserClient

  # --- Configuration ---
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the project unique 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",
  )

  project = user_client.get_project(PROJECT_ID)

  # --- 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))
  print(time_entries)
  ```

  ```python Timers - Projects  theme={"dark"}

  from collections import defaultdict
  from datetime import datetime

  from encord import EncordUserClient

  # --- Configuration ---
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the project unique 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",
  )

  project = user_client.get_project(PROJECT_ID)

  # --- 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))

  # Filters for total Project time
  total_time = sum(entry.time_spent_seconds for entry in time_entries)
  print(f"Total time for project: {total_time} sec ({total_time / 60:.1f} min)")

  ```

  ```python Timers - Stages  theme={"dark"}

  from collections import defaultdict
  from datetime import datetime

  from encord import EncordUserClient

  # --- Configuration ---
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the project unique 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",
  )

  project = user_client.get_project(PROJECT_ID)

  # --- 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))

  # Filters for total time by stage
  stage_time = defaultdict(int)
  for entry in time_entries:
      stage_time[entry.workflow_stage.title] += entry.time_spent_seconds

  for stage, seconds in sorted(stage_time.items(), key=lambda x: x[1], reverse=True):
      print(f"Stage: {stage:<25} | {seconds:>5} sec | {seconds / 60:>5.1f} min")

  ```

  ```python Timers - Tasks  theme={"dark"}

  from collections import defaultdict
  from datetime import datetime

  from encord import EncordUserClient

  # --- Configuration ---
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the project unique 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",
  )

  project = user_client.get_project(PROJECT_ID)

  # --- 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))

  # Filters for task time

  task_time = defaultdict(int)
  for entry in time_entries:
      task_time[str(entry.workflow_task_uuid)] += entry.time_spent_seconds

  for task, seconds in sorted(task_time.items(), key=lambda x: x[1], reverse=True):
      print(f"Task UUID: {task} | {seconds:>5} sec | {seconds / 60:>5.1f} min")
  ```

  ```python Timers - Users  theme={"dark"}

  from collections import defaultdict
  from datetime import datetime

  from encord import EncordUserClient

  # --- Configuration ---
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the project unique 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",
  )

  project = user_client.get_project(PROJECT_ID)

  # --- 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))

  # Filters for user

  user_time = defaultdict(int)
  for entry in time_entries:
      user_time[entry.user_email] += entry.time_spent_seconds

  for user, seconds in sorted(user_time.items(), key=lambda x: x[1], reverse=True):
      print(f"User: {user:<30} | {seconds:>5} sec | {seconds / 60:>5.1f} min")
  ```
</CodeGroup>


# Split Projects
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-split-projects



The following script splits a source Project into a number of child projects, each containing a specified number of labels from the source Project. The number of child Projects created depends on the total number of labels contained in the source Projects, and how many labels each child Project contains.

<Tip>The script can be re-run if it fails, since it checks for existing Project names before creating new Projects.</Tip>

In the main function of the following script, ensure that you:

* Replace \<private\_key\_path> with the file path to your private key.
* Replace \<project\_hash> with the hash of the Project you want to split.
* Replace \<projectsize> with the maximum number of labels you want each child Project to contain.
* Replace \<start\_number> with the index of the child Project you would like the code to start from. For example, if there are 5 child Projects, \<start\_number> = 1 will start from the second Project.

```python theme={"dark"}
# import dependencies
import typer
from encord import EncordUserClient, Project
from encord.objects import LabelRowV2
from pathlib import Path

# Prepare target Projects
def get_destination_projects(user_client: EncordUserClient, source_project: Project, n_target_projects: int) -> List[Project]:
    dest_project_ids = []
    for idx in range(n_target_projects):
        target_title = source_project.title + f" slice {idx + 1}" 
        if found_projects := user_client.get_projects(title_eq=target_title):
            if len(found_projects) > 1:
                print(f"A few projects with name {target_title} found. Can't proceed, as target name should be unique.")
                exit(1)
            if found_projects:
                dest_project_id = found_projects[0]["project"]["project_hash"]
                dest_project_ids.append(dest_project_id)
                continue
        dest_project_id = source_project.copy_project(copy_datasets=True, copy_collaborators=True, new_title=target_title)
        dest_project_ids.append(dest_project_id)

    print(f"Destination project ids: {dest_project_ids}")
    return [user_client.get_project(project_hash=p) for p in dest_project_ids]

# Prepare data for new Projects
def get_destination_label_row(destination_project: Project, data_hash: str) -> LabelRowV2:
    result = destination_project.list_label_rows_v2(data_hashes=[data_hash])
    if not result:
        print("No such data hash in the destination project, something wrong!")
        exit(1)
    return result[0]

# The main function. Substitute your variables here
def main(ssh_key: Path = "<private_key_path>", source_project: str = "<project_hash>", target_project_size: int = <project_size>, continue_from: int = <start_number>, ):

    user_client = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=ssh_key
    )

    project = user_client.get_project(project_hash=source_project)
    n_items = len(project.list_label_rows_v2())
    n_target_projects = int(n_items / target_project_size) + 1

    print(f"Project {project.title} has {n_items} entries.")
    if n_target_projects < 2:
        print("Nothing to do!")
        exit(0)
    print(f"Splitting source project into {n_target_projects} of size {target_project_size}")

    destination_projects = get_destination_projects(user_client, project, n_target_projects)

    source_label_rows = project.list_label_rows_v2()
    for idx, (src_label_row, destination_project) in enumerate(zip(source_label_rows, [p for p in destination_projects for _ in range(target_project_size)])):
        if continue_from > idx:
            continue

        src_label_row.initialise_labels()

        dst_label_row = get_destination_label_row(destination_project, src_label_row.data_hash)
        dst_label_row.initialise_labels()

        src = src_label_row.to_encord_dict()

        dst = dst_label_row.to_encord_dict()
        dst['object_answers'] = src['object_answers']
        dst['classification_answers'] = src['classification_answers']
        dst['object_actions'] = src['object_actions']
        dst['data_units'] = src['data_units']

        dst_label_row.from_labels_dict(dst)
        dst_label_row.save()
        print(f"{idx + 1}/{len(source_label_rows)}: '{src_label_row.data_title}' labels copied to project {destination_project.title}")

# Run the main function
if __name__ == "__main__":
    typer.run(main)
```


# Workflows and Stages
Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-workflows-stages



## Workflow Basics

Encord SDK supports programmatic use of Workflows with the following: `WorkflowStage`, `WorkflowAction`, and `Task`. Typical use would be querying a `WorkflowStage` to get `Tasks` matching some criteria, and then executing a `WorkflowAction` against Tasks (for example: assigning, submitting annotation tasks, or accepting review tasks). The type of actions available depends on the stage queried.

Here is a short description of major parts of the Workflows SDK:

<AccordionGroup>
  <Accordion title="WorkflowStage">
    * `WorkflowStage`: Move your tasks through a Workflow Project using the `WorkflowStage` class.
      * `AnnotationStage`
      * `ReviewStage`
      * `ConsensusAnnotationStage`
      * `ConsensusReviewStage`
      * `AgentStage`
      * `FinalStage` (Complete and Archive)
  </Accordion>

  <Accordion title="WorkflowAction">
    * `WorkflowAction`: Applies an action to a task in a workflow stage

      The following actions are supported:

      * `assign`: Assigns a user to one or more tasks.
      * `submit`: Moves a task to the next stage.
      * `release`: Releases a task from the current user.
      * `accept`: Accepts a task.
      * `reject`: Rejects a task.
  </Accordion>

  <Accordion title="Task">
    * `Task`: Exposes a simple version of the tasks available in a Project.
  </Accordion>

  <Accordion title="TaskStatus">
    * `TaskStatus`: The following statuses are available:

      The following statuses are available for ANNOTATE tasks:

      * `NEW`: Tasks that are unassigned.
      * `ASSIGNED`: Tasks that are assigned to a user.
      * `RELEASED`: Tasks that were released from an assigned user.
      * `REOPENED`: Tasks that were reopened.
      * `SKIPPED`: Tasks that were skipped by annotators.
      * `COMPLETED`: Tasks that are in the Complete stage. Used for Annotation sub-tasks in Consensus Annotation tasks.

    <Note>Consensus Annotation tasks consist of 1 or more Annotation sub-tasks.</Note>

    The following statuses are available for REVIEW and CONSENSUS REVIEW tasks:

    * `NEW`: Tasks that are unassigned.
    * `ASSIGNED`: Tasks that are assigned to a user.
    * `RELEASED`: Tasks that were released from an assigned user.
    * `REOPENED`: Tasks that were reopened.
  </Accordion>
</AccordionGroup>

<Warning>In Consensus Projects, tasks in the COMPLETE and ARCHIVE blocks CANNOT be reopened.</Warning>

#### View all stages in a Workflow

The following code provides you with the method to view all stages in a Workflow in a Project. The code is the same for Consensus and Non-Consensus Projects.

<Note>Routers are not displayed in the list of stages when using the SDK.</Note>

<CodeGroup>
  ```python Boilerplate theme={"dark"}

  # 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 Example theme={"dark"}

  # 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}")

  ```

  ```python Example Output - Non-Consensus Project theme={"dark"}

  Stage #0: AnnotationStage(stage_type=WorkflowStageType.ANNOTATION, uuid='2ed1d9f4-5b42-4959-bcbe-93eaf866320c', title='Annotate 1')
  Stage #1: ReviewStage(stage_type=WorkflowStageType.REVIEW, uuid='ddb7973d-bae9-4ced-8dcb-ec178e66dba0', title='Review 1')
  Stage #2: AnnotationStage(stage_type=WorkflowStageType.ANNOTATION, uuid='58ec51ba-2669-4036-b25c-17aecf805a59', title='Annotate 2')
  Stage #3: ReviewStage(stage_type=WorkflowStageType.REVIEW, uuid='8047e0d5-fc41-4ac5-a7ed-335b3dbd887f', title='Review 2')
  Stage #4: FinalStage(stage_type=WorkflowStageType.DONE, uuid='90fc8b51-6a2f-4de0-88d0-059f76865385', title='Complete')
  Stage #5: FinalStage(stage_type=WorkflowStageType.DONE, uuid='1432dbf0-5c19-41fe-a7b0-811d36b27456', title='Archive')

  ```

  ```python Example Output - Consensus Workflow Project theme={"dark"}

  Stage #0: ConsensusAnnotationStage(stage_type=WorkflowStageType.CONSENSUS_ANNOTATION, uuid='2adfe595-4a56-41f2-bfcc-eeab3dd58b65', title='Consensus 1')
  Stage #1: ConsensusReviewStage(stage_type=WorkflowStageType.CONSENSUS_REVIEW, uuid='1f37fb4c-a74a-4437-b33d-6fc4e3ccc2f5', title='Consensus 1 Review')
  Stage #2: ReviewStage(stage_type=WorkflowStageType.REVIEW, uuid='9fc321da-0e62-4cc5-b5e7-5ce8f73c3c20', title='Review 1')
  Stage #3: ConsensusAnnotationStage(stage_type=WorkflowStageType.CONSENSUS_ANNOTATION, uuid='518cd79f-a9a9-4ab9-bb92-3dcf0fae29a2', title='Consensus 2')
  Stage #4: ConsensusReviewStage(stage_type=WorkflowStageType.CONSENSUS_REVIEW, uuid='81e0cb65-69ae-4d3b-aac8-8917f1480930', title='Consensus 2 Review')
  Stage #5: FinalStage(stage_type=WorkflowStageType.DONE, uuid='fd5c3513-c7a5-42c3-a07c-933838aecf62', title='Complete')
  Stage #6: FinalStage(stage_type=WorkflowStageType.DONE, uuid='c67d08c5-b93b-49be-87b2-39809ea7b27a', title='Archive')

  ```
</CodeGroup>

**Non-Consensus Project**

This is an example of a non-Consensus Workflow graph.

<div>
  <img />
</div>

**Consensus Workflow Project**

This is an example of a Consensus Workflow graph.

<div>
  <img />
</div>

## Non-Consensus Projects

In the SDK, a class is defined for every stage type. This allows you to see what properties and actions each stage offers. The following stages are supported for non-Consensus Projects:

* `AnnotationStage`
* `ReviewStage`
* `FinalStage` (Complete and Archive)

```python theme={"dark"}

class AnnotationStage(WorkflowStage):
	uuid: str
	title: str
  
  def get_tasks()
    
```

`Tasks` provides programmatic access to your tasks available in the UI.\
The following tasks are supported for non-Consensus Projects::

* `assign`: Assigns a user to one or more tasks.
* `submit`: Moves a task to the next stage.
* `release`: Releases a task from the current user.

```python theme={"dark"}
class AnnotationTask:
    uuid: UUID
    data_hash: UUID
    data_title: str
    label_branch: str  # main by default
```

<AccordionGroup>
  <Accordion title="Display Tasks in a Stage">
    #### Display Tasks in a Stage

    Use the following scripts as templates for annotation and review tasks.

    ```python Display Stage Tasks theme={"dark"}

    # Import dependencies
    from encord import EncordUserClient, Project

    from encord.workflow import(
      AnnotationStage, 
      ReviewStage,
      ConsensusAnnotationStage, 
      ConsensusReviewStage,
      FinalStage
    )

    SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
    PROJECT_HASH = "<project-unique-id>"

    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)

    stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)
    # type_ is an optional parameter here, any other type narrowing technique can be used here
    # for example it can be an assert as follows
    assert isinstance(stage, AnnotationStage)

    for task in stage.get_tasks():
        print(f"Task: {task}")

    ```
  </Accordion>

  <Accordion title="Assign a User to Tasks in a Stage">
    #### Assign a User to Tasks in a Stage

    Use the following scripts as templates for annotation and review tasks.

    <CodeGroup>
      ```python Assign a User Template theme={"dark"}

      from encord.user_client import EncordUserClient
      from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
      from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
      from encord.workflow.stages.consensus_review import ConsensusReviewStage
      from encord.workflow.stages.review import ReviewStage

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

      PROJECT_ID="<project-unique-id>"

      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      project = user_client.get_project(PROJECT_ID)

      workflow = project.workflow

      annotation_stage = workflow.get_stage(name="<name-of-workflow-stage>", type_=<type-of-workflow-stage>)

      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for annotation_task in annotation_stage.get_tasks():
              print(annotation_task.data_title)
              
              # Assign task to someone
              annotation_task.assign(assignee='<email-address>', bundle=bundle)

      ```

      ```python Example theme={"dark"}

      from encord.user_client import EncordUserClient
      from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
      from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
      from encord.workflow.stages.consensus_review import ConsensusReviewStage
      from encord.workflow.stages.review import ReviewStage

      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID="<project-unique-id>"

      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      project = user_client.get_project(PROJECT_ID)

      workflow = project.workflow

      annotation_stage = workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for annotation_task in annotation_stage.get_tasks():
              print(annotation_task.data_title)
              
              # Assign task to someone
              annotation_task.assign(assignee='chris@acme.com', bundle=bundle)

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Submit Tasks as Another User in a Stage">
    #### Submit Tasks as Another User in a Stage

    <Info>
      * Annotation Tasks can only be submitted on behalf of users with the following roles: Annotator, Annotator + Reviewer, Team Manager, or Admin.
      * Review Tasks can only be submitted on behalf of users with the following roles: Reviewer, Annotator + Reviewer, Team Manager, or Admin.
    </Info>

    <CodeGroup>
      ```python Submit Annotation Tasks as Another User theme={"dark"}

      from encord.user_client import EncordUserClient
      from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
      from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
      from encord.workflow.stages.consensus_review import ConsensusReviewStage
      from encord.workflow.stages.review import ReviewStage

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

      PROJECT_ID="<project-unique-id>"

      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      project = user_client.get_project(PROJECT_ID)

      workflow = project.workflow

      annotation_stage = workflow.get_stage(name="<name-of-annotation-stage>", type_=<type-of-workflow-stage>)

      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for annotation_task in annotation_stage.get_tasks():
              print(annotation_task.data_title)
              
              # Submit as someone explicitly
              annotation_task.submit(assignee='<email-address>', bundle=bundle)

      ```

      ```python Submit Review Tasks as Another User theme={"dark"}

      from encord.user_client import EncordUserClient
      from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
      from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
      from encord.workflow.stages.consensus_review import ConsensusReviewStage
      from encord.workflow.stages.review import ReviewStage

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

      PROJECT_ID="<project-unique-id>"

      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      project = user_client.get_project(PROJECT_ID)

      workflow = project.workflow

      review_stage = workflow.get_stage(name="<name-of-review-stage>", type_=<type-of-workflow-stage>)

      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for review_task in annotation_stage.get_tasks():
              print(review_task.data_title)
              
              # Submit as someone explicitly
              review_task.submit(assignee='<email-address>', bundle=bundle)

      ```

      ```python Example theme={"dark"}

      from encord.user_client import EncordUserClient
      from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
      from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
      from encord.workflow.stages.consensus_review import ConsensusReviewStage
      from encord.workflow.stages.review import ReviewStage

      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID="<project-unique-id>"

      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      project = user_client.get_project(PROJECT_ID)

      workflow = project.workflow

      annotation_stage = workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for annotation_task in annotation_stage.get_tasks():
              print(annotation_task.data_title)
              
              # Submit as someone explicitly
              annotation_task.submit(assignee='chris@acme.com', bundle=bundle)

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Retain Current User and Submit Task">
    #### Retain Current User and Submit Task

    <Info>
      * Annotation Tasks can only be submitted by users with the following roles: Annotator, Annotator + Reviewer, Team Manager, or Admin.
      * Review Tasks can only be submitted by users with the following roles: Reviewer, Annotator + Reviewer, Team Manager, or Admin.
    </Info>

    <CodeGroup>
      ```python Retain Current User and Submit Annotation Task theme={"dark"}

      from encord.user_client import EncordUserClient
      from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
      from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
      from encord.workflow.stages.consensus_review import ConsensusReviewStage
      from encord.workflow.stages.review import ReviewStage

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

      PROJECT_ID="<project-unique-id>"

      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      project = user_client.get_project(PROJECT_ID)

      workflow = project.workflow

      annotation_stage = workflow.get_stage(name="<name-of-workflow-stage>", type_=<type-of-workflow-stage>)

      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for annotation_task in annotation_stage.get_tasks():
              print(annotation_task.data_title)
              
              # Retain current assignee and submit
              annotation_task.submit(retain_assignee=True, bundle=bundle)

      ```

      ```python Retain Current User and Submit Review Task theme={"dark"}

      from encord.user_client import EncordUserClient
      from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
      from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
      from encord.workflow.stages.consensus_review import ConsensusReviewStage
      from encord.workflow.stages.review import ReviewStage

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

      PROJECT_ID="<project-unique-id>"

      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      project = user_client.get_project(PROJECT_ID)

      workflow = project.workflow

      review_stage = workflow.get_stage(name="<name-of-review-stage>", type_=<type-of-workflow-stage>)

      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for review_task in review_stage.get_tasks():
              print(review_task.data_title)
              
              # Retain current assignee and submit
              review_task.submit(retain_assignee=True, bundle=bundle)

      ```

      ```python Example theme={"dark"}

      from encord.user_client import EncordUserClient
      from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
      from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
      from encord.workflow.stages.consensus_review import ConsensusReviewStage
      from encord.workflow.stages.review import ReviewStage

      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

      PROJECT_ID="<project-unique-id>"

      user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      project = user_client.get_project(PROJECT_ID)

      workflow = project.workflow

      annotation_stage = workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for annotation_task in annotation_stage.get_tasks():
              print(annotation_task.data_title)
              
              # Retain current assignee and submit
              annotation_task.submit(retain_assignee=True, bundle=bundle)

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Get all Tasks">
    #### Get all Tasks

    ```python Get Tasks theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient, Project

    from encord.workflow import(
      AnnotationStage, 
      ReviewStage,
      ConsensusAnnotationStage, 
      ConsensusReviewStage,
      FinalStage
    )

    SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
    PROJECT_HASH = "<project-unique-id>"

    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)

    stage = project.workflow.get_stage(name="Consensus 1", type_=ConsensusAnnotationStage)
    # type_ is an optional parameter here, any other type narrowing technique can be used here
    # for example it can be an assert like follows
    assert isinstance(stage, ConsensusAnnotationStage)

    for task in stage.get_tasks():
        
        print(f"Task: {task}")

    ```
  </Accordion>

  <Accordion title="Filter tasks by data hash">
    #### Filter tasks by data hash

    You can filter tasks in any stage using data hashes.

    ```python Filter tasks by data hash theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient, Project
    from encord.workflow import AnnotationStage, ReviewStage, ConsensusAnnotationStage, ConsensusReviewStage, FinalStage

    # Constants
    SSH_PATH = "<ssh-private-key>"
    PROJECT_HASH = "<project-unique-id>"

    # Create user client
    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)

    # Get stage
    stage = project.workflow.get_stage(name="Review 1", type_=ReviewStage)
    # Uncomment the following line for different stage
    # stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

    # Check instance type. Change the type for each stage
    assert isinstance(stage, ReviewStage)

    # List of data hashes.
    data_hashes = ["<data-unique-id-01>", "<data-unique-id-02>", "<data-unique-id-03>"]

    for task in stage.get_tasks(data_hash=data_hashes):
        print(f"Task: {task}")

    ```
  </Accordion>

  <Accordion title="Move all tasks in a stage to the next stage">
    #### Move all tasks in a stage to the next stage

    You can submit tasks as the currently assigned user or as a different user. If you do not specify the user to submit the task, you are assigned as the user submitting the task.

    <CodeGroup>
      ```python Submit tasks as currently assigned user theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient, Project
      from encord.workflow import AnnotationStage

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

      # Authenticate
      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)

      # Get the specific stage (in this case, "Annotate 1")
      stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)
      assert isinstance(stage, AnnotationStage)

      # Define bundle size
      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      # Create a bundle and move tasks
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          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)
              print(f"Task: {task}")

      print("All tasks have been processed and moved to the next stage.")

      ```

      ```python Submit tasks as another user theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient, Project
      from encord.workflow import AnnotationStage

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

      # Authenticate
      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)

      # Get the specific stage (in this case, "Annotate 1")
      stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)
      assert isinstance(stage, AnnotationStage)

      # Define bundle size
      BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

      # Create a bundle and move tasks
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for task in stage.get_tasks():
              # The task is submitted as the user you specify.
              task.submit(assignee='<email-of-user-you-want-as-assignee>', bundle=bundle)
              print(f"Task: {task}")

      print("All tasks have been processed and moved to the next stage.")

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Use model predictions as an annotator">
    #### Use model predictions as an annotator

    ```python theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient, Project

    from encord.workflow import (
        AnnotationStage,
        ReviewStage,
        ConsensusAnnotationStage,
        ConsensusReviewStage,
        FinalStage,
    )

    SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
    PROJECT_HASH = "<project-unique-id>"

    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)

    stage = project.workflow.get_stage(name="Automated Annotation", type_=AnnotationStage)
    assert isinstance(stage, AnnotationStage)

    BUNDLE_SIZE = 100  # Define bundle size

    # Assign tasks in bundles
    with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
        for task in stage.get_tasks():
            task.assign("admin-alex@encord.com", bundle=bundle)
            print(f"Task assigned: {task}")

    # Initialize label rows using bundles
    with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
        for task in stage.get_tasks():
            if match_some_criteria(task):
                label_rows = project.list_label_rows_v2(data_hashes=[task.data_hash])
                for label_row in label_rows:
                    label_row.initialise_labels(bundle=bundle)

                    # Custom logic that populates label rows with labels
                    do_preannotate(label_row)

    # Save label rows using bundles
    with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
        for task in stage.get_tasks():
            if match_some_criteria(task):
                label_rows = project.list_label_rows_v2(data_hashes=[task.data_hash])
                for label_row in label_rows:
                    label_row.save(bundle=bundle)

    # Submit tasks in bundles
    with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
        for task in stage.get_tasks():
            if match_some_criteria(task):
                task.submit(bundle=bundle)
                print(f"Task submitted: {task}")
    ```
  </Accordion>
</AccordionGroup>

## Consensus Projects

Consensus annotation tasks can be listed, but cannot be assigned or moved into the Consensus review stage. In Consensus Projects, tasks are broken into subtasks. One subtask for each Annotator. Subtasks can be assigned or submitted.

Consensus Projects support the following stages:

* `AnnotationStage`
* `ReviewStage`
* `ConsensusAnnotationStage`
* `ConsensusReviewStage`
* `FinalStage` (Complete and Archive)

The following actions are supported for Consensus review and Review and Refine:

* `assign`: Assigns a user to one or more tasks.
* `approve`: Moves a task to the next stage.
* `release`: Releases a task from the current user.
* `reject`: Rejects a task.

<AccordionGroup>
  <Accordion title="Get all Subtasks">
    #### Get all Subtasks

    ```python Get Subtasks theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient, Project

    from encord.workflow import(
      AnnotationStage, 
      ReviewStage,
      ConsensusAnnotationStage, 
      ConsensusReviewStage,
      FinalStage
    )

    SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
    PROJECT_HASH = "<project-unique-id>"

    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)

    stage = project.workflow.get_stage(name="Consensus 1", type_=ConsensusAnnotationStage)
    # type_ is an optional parameter here, any other type narrowing technique can be used here
    # for example it can be an assert like follows
    assert isinstance(stage, ConsensusAnnotationStage)

    for task in stage.get_tasks():
        
        print(f"Task: {task}")
        for subtask in task.subtasks:
            print(f"   subtask: {subtask}")

    ```
  </Accordion>

  <Accordion title="Select your labels from a Consensus Project">
    #### Select your labels from a Consensus Project

    The following code includes `produce_result`, that is undefined. You need to create and define the custom logic that selects the labels from the label options you have available.

    ```python theme={"dark"}

    # Import dependencies
    from encord import EncordUserClient, Project

    from encord.workflow import(
      AnnotationStage, 
      ReviewStage,
      ConsensusAnnotationStage, 
      ConsensusReviewStage,
      FinalStage
    )

    SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
    PROJECT_HASH = "<project-unique-id>"

    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)

    # Obtaining the stage
    stage = project.workflow.get_stage(name="Consensus 1 Review", type_=ConsensusReviewStage)

    BUNDLE_SIZE = 100  # Define bundle size

    # Get all the tasks (or rather iterator over tasks), 
    # Do NOT download them all at once.
    for task in stage.get_tasks():
        # Each consensus branch has a unique label hash, so use them as filter
        label_hashes = [option.label_hash for option in task.options]
        label_rows_for_consensus = project.list_label_rows_v2(label_hashes=label_hashes)

        target_label_row = project.list_label_rows_v2(data_hashes=[task.data_hash])[0]
       
        with project.create_bundle(bundle_size=BUNDLE_SIZE) as label_initialize_bundle:
            # Bundling all our initialization operations in one operation
            for label_row in label_rows_for_consensus:
                label_row.initialise_labels(bundle=label_initialize_bundle)

            target_label_row.initialise_labels(bundle=label_initialize_bundle)

        # Download labels
        for label_row in label_rows_for_consensus:
            # Perform custom user logic and populate the target label row.
            # This means defining produce_result in your custom logic as produce_result
            # is not defined in the Encord SDK.
            if is_consensus := produce_result(label_rows_for_consensus, target_label_row):
                target_label_row.save()
                task.assign("<your-admin@example.com>")
                task.approve()
            else:
                task.reject()

    ```
  </Accordion>
</AccordionGroup>

## Move Tasks

### To Next Stage

Submitting a task moves it to the next stage in the Workflow.

```python Submit Task To Next Stage theme={"dark"}
from encord.user_client import EncordUserClient
from encord.workflow.stages.annotation import AnnotationStage, AnnotationTaskStatus
from encord.workflow.stages.consensus_annotation import ConsensusAnnotationStage
from encord.workflow.stages.consensus_review import ConsensusReviewStage
from encord.workflow.stages.review import ReviewStage

SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

PROJECT_ID="<project-unique-id>"

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

project = user_client.get_project(PROJECT_ID)

workflow = project.workflow

annotation_stage = workflow.get_stage(name="Annotate 1", type_=AnnotationStage)

BUNDLE_SIZE = 100  # You can adjust this value as needed, but keep it <= 1000

with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for annotation_task in annotation_stage.get_tasks():
        print(annotation_task.data_title)
        
        # Submit as someone explicitly
        annotation_task.submit(assignee='chris@acme.com', bundle=bundle)
```

### To Complete

[workflow\_complete()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#workflow_complete) moves Workflow tasks to the *Complete* stage.

<Warning>In Consensus Projects, tasks in the COMPLETE and ARCHIVE blocks CANNOT be reopened.</Warning>

<CodeGroup>
  ```python All Tasks theme={"dark"}
  # Import dependencies
  from encord.user_client 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>"
      )

  # Open the project you want to work on by specifying the project hash
  project = user_client.get_project(
      "<project-hash>"
  )

  # Create a bundle
  with project.create_bundle() as bundle:
      # Move all tasks into the final stage of the Workflow
      for label_row in project.list_label_rows_v2():
          label_row.workflow_complete(bundle=bundle)
  ```

  ```python From Specific Stage theme={"dark"}
  # Import dependencies
  from encord.user_client 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>')

  # Open the project you want to work on by specifying the project hash
  project = user_client.get_project(
      "<project-hash>"
  )

  # Move all tasks from <review_stage_2> into the final stage of the Workflow project
  for label_row in project.list_label_rows_v2():
      if label_row.workflow_graph_node.title == "<review_stage_2>":
          label_row.workflow_complete()

  ```
</CodeGroup>

### Reopen

Use the [workflow\_reopen()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#workflow_reopen) method to reopen tasks. Reopening tasks moves tasks back to the first stage in your Workflow.

<CodeGroup>
  ```python Reopen all Tasks theme={"dark"}
  # Import dependencies
  from encord.user_client 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>"
      )

  # Open the project you want to work on by specifying the project hash
  project = user_client.get_project(
      "<project-hash>"
  )

  # Create a bundle and automatically execute everything attached to the bundle
  with project.create_bundle() as bundle:
      # Return all data units in the task back to the first Workflow stage
      for label_row in project.list_label_rows_v2():
          label_row.workflow_reopen(bundle=bundle)
  ```

  ```python Reopen Specific Task theme={"dark"}
  # Import dependencies
  from encord.user_client 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>"
      )

  # Open the project you want to work on by specifying the project hash
  project = user_client.get_project(
      "<project-hash>"
  )

  # Create a bundle and automatically execute everything attached to the bundle
  with project.create_bundle() as bundle:
      # Return all data units in the task back to the first Workflow stage
      for label_row in project.list_label_rows_v2():
          # Return the first label row to the first Workflow stage
          label_row[0].workflow_reopen()
  ```
</CodeGroup>

### Move Tasks Freely

<Warning>
  * Moving tasks skips all intermediate Workflow stages, placing them immediately into the selected stage.
  * All labels (object and classification) are automatically approved when tasks move to a COMPLETE stage.
  * Webhooks do not fire when tasks teleport through a workflow.
</Warning>

This script shows how to move a data unit directly between workflow stages, bypassing the standard workflow progression. The script shows how to access various Workflow Stage types; you should only use the ones relevant to your project.

```python Moving Tasks theme={"dark"}
from encord import EncordUserClient
from encord.workflow import AnnotationStage, ReviewStage,  AgentStage, FinalStage, ConsensusAnnotationStage

PROJECT_ID = '<project_ID>'
DATA_HASH = '<data_unit_hash>'
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path='<private_key_path>'
)

project = user_client.get_project(PROJECT_ID)

# Get your required stages
consensus_annotation_stage = project.workflow.get_stage(name='Consensus 1', type_=ConsensusAnnotationStage)
annotation_stage = project.workflow.get_stage(name='Annotate 1', type_=AnnotationStage)
review_stage = project.workflow.get_stage(name='Review 1', type_=ReviewStage)
agent_stage = project.workflow.get_stage(name='Agent 1', type_=AgentStage)
complete_stage = project.workflow.get_stage(name='Complete', type_=FinalStage)
archive_stage = project.workflow.get_stage(name='Archive', type_=FinalStage)

# Insert source and destination stages here
source_stage = <insert_source_stage>
destination_stage = <insert_destination_stage>

# Move a task from the source stage to the destination stage
with project.create_bundle() as bundle:
    for task in source_stage.get_tasks(data_hash=DATA_HASH):
        print(f"Moving task from '{source_stage.name}' to '{destination_stage.name}'")
        task.move(destination_stage_uuid=destination_stage.uuid, bundle=bundle)
```

***

## Task Priority

You can read and assign task priorities using the SDK. Priorities in the SDK are represented by numbers ranging from 0 to 1, where 1 corresponds to `100` in the Encord platform, the highest priority value.

<Tip>For more information, see our platform documentation for the [*Queue* tab](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-queue-and-workflow), and [priorities](/platform-documentation/Annotate/annotate-projects/annotate-manage-annotation-projects#task-priority).</Tip>

<Note>You cannot set the priority for more than 100 tasks in a bundle.</Note>

<CodeGroup>
  ```python One Task theme={"dark"}
  # Import dependencies
  from encord.user_client 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>"
      )

  # Open the project you want to work on by specifying the project hash
  project = user_client.get_project(
      "<project-hash>"
  )

  # Reading the priority of the first label row
  label_row = project.list_label_rows_v2()[0]
  label_row.initialise_labels()

  print(f"Current priority: {label_row.priority}")

  # Setting the priority of the first label row to 0.2
  label_row.set_priority(0.2)
  label_row = project.list_label_rows_v2()[0]
  print(f"New priority: {label_row.priority}")
  ```

  ```python Multiple Tasks theme={"dark"}
  # Import dependencies
  from encord.user_client 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>"
      )

  # Open the project you want to work on by specifying the project hash
  project = user_client.get_project(
      "<project-hash>"
  )

  # Create a bundle
  with project.create_bundle() as bundle:

  # Set the priority of all tasks in the project to 0.5 
    for label_row in project.list_label_rows_v2():
      label_row.set_priority(0.5, bundle=bundle)
  ```
</CodeGroup>

***

## End-to-End Example moving tasks through Projects

This example uses a basic non-Consensus Project Workflow moving a number of tasks from ANNOTATE to COMPLETE.

[!End-to-end Example Workflow](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/e2e-sdk-workflow-001.png)

[!End-to-end Example tasks](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/e2e-sdk-workflow-002.png)

* Project ID: 01bd7084-b04a-4cd1-87f3-73e8e78925c4
* Data units: apples\_01.jpg, apples\_02.jpg, apples\_03.jpg, apples\_04.jpg, apples\_05.jpg

<AccordionGroup>
  <Accordion title="STEP 1: View all tasks in the Project">
    A few tasks have been annotated, but they have not been submitted yet. The following code lists all tasks in the ANNOTATE 1 stage.

    <CodeGroup>
      ```python Lists all tasks in ANNOTATE 1 theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient, Project

      from encord.workflow import(
        AnnotationStage, 
        ReviewStage,
        ConsensusAnnotationStage, 
        ConsensusReviewStage,
        FinalStage
      )


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "01bd7084-b04a-4cd1-87f3-73e8e78925c4"

      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)

      stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)
      # type_ is an optional parameter here, any other type narrowing technique can be used here
      # for example it can be an assert like follows
      assert isinstance(stage, AnnotationStage)

      for task in stage.get_tasks():
          
          print(f"Task: {task}")
      ```

      ```python Result theme={"dark"}
      Task: uuid=UUID('387dbbe6-4abb-47f8-9efe-199d1d4652ce') created_at=datetime.datetime(2024, 6, 28, 17, 19, 10, 374492) updated_at=datetime.datetime(2024, 6, 30, 22, 51, 51, 139841) data_hash=UUID('34571f50-90d1-4681-a58b-1fd08e9f6665') data_title='apples_05.jpg' label_branch_name='main' assignee=None
      Task: uuid=UUID('80e09443-f649-4624-9cff-222c04115d16') created_at=datetime.datetime(2024, 6, 28, 17, 19, 10, 374492) updated_at=datetime.datetime(2024, 6, 30, 22, 53, 58, 858513) data_hash=UUID('22f8dc9a-deff-49a2-a2d2-3863cf20d4f4') data_title='apples_03.jpg' label_branch_name='main' assignee='annotator003@encord.com'
      Task: uuid=UUID('d5fa67aa-9490-4248-ad0d-287b5dc23189') created_at=datetime.datetime(2024, 6, 28, 17, 19, 10, 374492) updated_at=datetime.datetime(2024, 6, 30, 22, 52, 15, 119658) data_hash=UUID('809344fd-8935-4dde-81eb-36efb4e6d558') data_title='apples_01.jpg' label_branch_name='main' assignee='annotator001@encord.com'
      Task: uuid=UUID('e53132b4-fd13-4673-bf65-41fe8e690125') created_at=datetime.datetime(2024, 6, 28, 17, 19, 10, 374492) updated_at=datetime.datetime(2024, 6, 30, 22, 55, 9, 87875) data_hash=UUID('4dc183ba-4233-4cb1-a940-cb6b2bc38f35') data_title='apples_04.jpg' label_branch_name='main' assignee='annotator-reviewer001@encord.com'
      Task: uuid=UUID('e793424c-1d2f-4f32-aa18-920ada4b2a7a') created_at=datetime.datetime(2024, 6, 28, 17, 19, 10, 374492) updated_at=datetime.datetime(2024, 6, 30, 22, 52, 48, 962443) data_hash=UUID('36b0afd3-6ff8-4201-bf65-35a37f6fe5b5') data_title='apples_02.jpg' label_branch_name='main' assignee='annotator002@encord.com'
      ```
    </CodeGroup>

    From the returned results we can see that four of the data units have been assigned (apples\_01 to apples\_04) while one task has not (apples\_05). We do not know the extent that each of the assigned data units has been annotated, but we want the tasks to move through the Workflow.
  </Accordion>

  <Accordion title="STEP 2: Submit all tasks for review">
    The following code submits ALL tasks to the REVIEW 1 stage. Before the tasks can be submitted they are first assigned to a user in the Project. The user could be any user capable of annotating in the Project (because this is the ANNOTATE stage). For this example, the Admin of the Project (the user with SDK access) is assigned.

    ```python Submit all tasks for review theme={"dark"}
    # Import dependencies
    from encord import EncordUserClient, Project

    from encord.workflow import(
      AnnotationStage, 
      ReviewStage,
      ConsensusAnnotationStage, 
      ConsensusReviewStage,
      FinalStage
    )

    SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
    PROJECT_HASH = "01bd7084-b04a-4cd1-87f3-73e8e78925c4"

    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)

    stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)
    # type_ is an optional parameter. Any type of narrowing technique can be used here.
    # For example:
    assert isinstance(stage, AnnotationStage)

    BUNDLE_SIZE = 100

    with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
        for task in stage.get_tasks():

            task.assign("chris@acme.com")

            task.submit(bundle=bundle)
            
            print(f"Task: {task}")
    ```
  </Accordion>

  <Accordion title="STEP 3: Verify that the tasks are in REVIEW 1">
    Each time we perform an action, we should verify the action is successful. After submitting the tasks, we can verify that the tasks are now in REVIEW 1.

    <CodeGroup>
      ```python Verify the tasks are in REVIEW 1 theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient, Project

      from encord.workflow import(
        AnnotationStage, 
        ReviewStage,
        ConsensusAnnotationStage, 
        ConsensusReviewStage,
        FinalStage
      )


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "01bd7084-b04a-4cd1-87f3-73e8e78925c4"

      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)

      stage = project.workflow.get_stage(name="Review 1", type_=ReviewStage)
      # type_ is an optional parameter here, any other type narrowing technique can be used here
      # for example it can be an assert like follows
      assert isinstance(stage, ReviewStage)

      for task in stage.get_tasks():
          
          print(f"Task: {task}")
      ```

      ```python Result theme={"dark"}
      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('02ace181-87dd-4628-8b17-7f9f16015c43') created_at=datetime.datetime(2024, 6, 30, 23, 15, 26, 636022) updated_at=datetime.datetime(2024, 6, 30, 23, 15, 26, 709843) assignee=None data_hash=UUID('34571f50-90d1-4681-a58b-1fd08e9f6665') data_title='apples_05.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'
      ```
    </CodeGroup>

    All of the tasks are now in stage REVIEW 1. None of the tasks are assigned to any users.
  </Accordion>

  <Accordion title="STEP 4: Reject a task">
    We know that `apples-05.jpg` does not have any labels, because it was not assigned to any users before we submitted the task. If we REJECT the task, according to the Workflow in the Project, the task returns to the ANNOTATE 1 stage.

    The following code filters the task in the REVIEW 1 stage based on the task's data hash, and then rejects the task.

    <CodeGroup>
      ```python theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient, Project
      from encord.workflow import AnnotationStage, ReviewStage, ConsensusAnnotationStage, ConsensusReviewStage, FinalStage
      from uuid import UUID  # Import the UUID function

      # Constants
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "01bd7084-b04a-4cd1-87f3-73e8e78925c4"

      # Create user client
      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)

      # Get stage
      stage = project.workflow.get_stage(name="Review 1", type_=ReviewStage)
      # Uncomment the following line for different stage

      # Check instance type
      assert isinstance(stage, ReviewStage)

      data_hashes = ["34571f50-90d1-4681-a58b-1fd08e9f6665"]

      BUNDLE_SIZE = 100

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for task in stage.get_tasks(data_hash=data_hashes):

              task.assign("chris@acme.com")

              task.reject(bundle=bundle)

              print(f"Task: {task}")
      ```

      ```python Returns theme={"dark"}
      Task: uuid=UUID('02ace181-87dd-4628-8b17-7f9f16015c43') created_at=datetime.datetime(2024, 6, 30, 23, 15, 26, 636022) updated_at=datetime.datetime(2024, 6, 30, 23, 15, 26, 709843) assignee=None data_hash=UUID('34571f50-90d1-4681-a58b-1fd08e9f6665') data_title='apples_05.jpg'
      ```
    </CodeGroup>

    From what was returned, we can see that only data unit `apples_05.jpg` was acted upon.

    To verify that the task is now in ANNOTATE 1, run the following:

    <CodeGroup>
      ```python Verify task is in ANNOTATE 1 theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient, Project

      from encord.workflow import(
        AnnotationStage, 
        ReviewStage,
        ConsensusAnnotationStage, 
        ConsensusReviewStage,
        FinalStage
      )


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "01bd7084-b04a-4cd1-87f3-73e8e78925c4"

      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)

      stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)
      # type_ is an optional parameter here, any other type narrowing technique can be used here
      # for example it can be an assert like follows
      assert isinstance(stage, AnnotationStage)

      for task in stage.get_tasks():
          
          print(f"Task: {task}")
      ```

      ```python Returns theme={"dark"}
      Task: uuid=UUID('387dbbe6-4abb-47f8-9efe-199d1d4652ce') created_at=datetime.datetime(2024, 6, 28, 17, 19, 10, 374492) updated_at=datetime.datetime(2024, 6, 30, 23, 48, 3, 805733) data_hash=UUID('34571f50-90d1-4681-a58b-1fd08e9f6665') data_title='apples_05.jpg' label_branch_name='main' assignee='chris@acme.com'
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="STEP 5: Approve tasks">
    There are still four tasks in REVIEW 1. The following code approves the tasks. This moves the tasks to the COMPLETE stage. You could approve all the tasks at once the REVIEW 1 stage, but instead we will filter by data hash and then approve.

    <CodeGroup>
      ```python Approve the tasks using data hashes theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient, Project
      from encord.workflow import AnnotationStage, ReviewStage, ConsensusAnnotationStage, ConsensusReviewStage, FinalStage
      from uuid import UUID  # Import the UUID function

      # Constants
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "01bd7084-b04a-4cd1-87f3-73e8e78925c4"

      # Create user client
      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)

      # Get stage
      stage = project.workflow.get_stage(name="Review 1", type_=ReviewStage)
      # Uncomment the following line for different stage

      # Check instance type
      assert isinstance(stage, ReviewStage)

      data_hashes = [
          "36b0afd3-6ff8-4201-bf65-35a37f6fe5b5",
          "4dc183ba-4233-4cb1-a940-cb6b2bc38f35",
          "22f8dc9a-deff-49a2-a2d2-3863cf20d4f4",
          "809344fd-8935-4dde-81eb-36efb4e6d558"
          ]



      BUNDLE_SIZE = 100

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for task in stage.get_tasks(data_hash=data_hashes):

              task.assign("chris@acme.com")

              task.approve(bundle=bundle)

              print(f"Task: {task}")
      ```

      ```python Returns theme={"dark"}
      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'
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="STEP 6: Verify tasks are COMPLETE">
    Use the following code to verify that the tasks `apples01` to `apples_04` are in the COMPLETE stage.

    <CodeGroup>
      ```python Verify tasks are COMPLETE theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient, Project

      from encord.workflow import(
        AnnotationStage, 
        ReviewStage,
        ConsensusAnnotationStage, 
        ConsensusReviewStage,
        FinalStage
      )


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_HASH = "09765dc5-08b0-4b32-b37a-e1b932b8b684"

      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)

      stage = project.workflow.get_stage(name="Complete", type_=FinalStage)
      # type_ is an optional parameter here, any other type narrowing technique can be used here
      # for example it can be an assert like follows
      assert isinstance(stage, FinalStage)

      for task in stage.get_tasks():
          
          print(f"Task: {task}")
      ```

      ```python Returns theme={"dark"}
      Task: uuid=UUID('e27acb09-0300-4bc9-8143-d0b837fd9207') created_at=datetime.datetime(2024, 7, 1, 0, 18, 22, 448867) updated_at=datetime.datetime(2024, 7, 1, 0, 18, 22, 495702) data_hash=UUID('22f8dc9a-deff-49a2-a2d2-3863cf20d4f4') data_title='apples_03.jpg'
      Task: uuid=UUID('23351c59-32a6-42b9-8e06-fe20c41513bc') created_at=datetime.datetime(2024, 7, 1, 0, 18, 22, 67363) updated_at=datetime.datetime(2024, 7, 1, 0, 18, 22, 110112) data_hash=UUID('4dc183ba-4233-4cb1-a940-cb6b2bc38f35') data_title='apples_04.jpg'
      Task: uuid=UUID('9e8fce04-af0e-41ca-926a-56bf354a2cba') created_at=datetime.datetime(2024, 7, 1, 0, 18, 21, 168387) updated_at=datetime.datetime(2024, 7, 1, 0, 18, 21, 223495) data_hash=UUID('36b0afd3-6ff8-4201-bf65-35a37f6fe5b5') data_title='apples_02.jpg'
      Task: uuid=UUID('41d98c6d-2f4c-4ad1-8f91-576b74e56600') created_at=datetime.datetime(2024, 7, 1, 0, 18, 20, 516722) updated_at=datetime.datetime(2024, 7, 1, 0, 18, 20, 561088) data_hash=UUID('809344fd-8935-4dde-81eb-36efb4e6d558') data_title='apples_01.jpg'
      ```
    </CodeGroup>

    And from what the code returns, the tasks are now in the COMPLETE stage.
  </Accordion>
</AccordionGroup>


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



Audio files support annotation using audio region object labels and classifications. Audio regions can be applied to a range (duration in milliseconds) on the audio file. Classifications can only be applied to the entire audio file. Using the Encord SDK you can import audio region labels and classifications directly to audio files that already exist in an Annotate Project. You can also use the SDK to view labels and classifications that exist on an audio file.

## Critical Information

Using classifications on an audio file is similar to using labels or classifications on a video file. There are some critical differences though:

* 1 "frame" = 1 millisecond for audio files when importing classifications.

* When creating a classification for an audio file, the `classification_instance` uses the `range_only=True` argument.

For example, `Classification.create_instance(range_only=True)` or `classification_instance = ClassificationInstance(range_only=True)`

```python theme={"dark"}

ranges = []
for range in classification_instance.get_ranges():
   ranges.append([range.start, range.end])

```

## Audio Regions on Audio Files

### Export Audio Regions on Audio Files

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from pathlib import Path
  from encord import EncordUserClient, Project
  import json

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

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

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

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

  # Initialize label rows using bundles
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Output directory for JSON files
  output_dir = Path("./label_exports")
  output_dir.mkdir(exist_ok=True)

  # Export each label row to a JSON file
  for label_row in label_rows:
      # Convert label row to dictionary
      label_data = label_row.to_encord_dict()

      # Save the label data to a JSON file
      file_name = f"{label_row.data_title}.json"
      output_path = output_dir / file_name

      with open(output_path, "w", encoding="utf-8") as json_file:
          json.dump(label_data, json_file, indent=4)

      print(f"Exported {label_row.data_title} to {output_path}")

  print("All labels have been exported!")

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from pathlib import Path
  from encord import EncordUserClient, Project
  import json

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_HASH = "55ee05af-1762-478c-9b3c-d43b4ad39ad4"

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

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

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

  # Initialize label rows using bundles
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Output directory for JSON files
  output_dir = Path("./label_exports")
  output_dir.mkdir(exist_ok=True)

  # Export each label row to a JSON file
  for label_row in label_rows:
      # Convert label row to dictionary
      label_data = label_row.to_encord_dict()

      # Save the label data to a JSON file
      file_name = f"{label_row.data_title}.json"
      output_path = output_dir / file_name

      with open(output_path, "w", encoding="utf-8") as json_file:
          json.dump(label_data, json_file, indent=4)

      print(f"Exported {label_row.data_title} to {output_path}")

  print("All labels have been exported!")

  ```
</CodeGroup>

### Import Audio Regions to Audio Files

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from pathlib import Path

  from encord import EncordUserClient, Project
  from encord.objects import (
      Object,
      ObjectInstance,
  )
  from encord.objects.coordinates import AudioCoordinates
  from encord.objects.frames import Range

  SSH_PATH = "<fie-path-to-your-ssh-key>"
  PROJECT_HASH = "<project-unique-id>"

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

  # Get the project for which predictions are to be added
  project: Project = user_client.get_project(PROJECT_HASH)

  # Example mapping of data unit titles to start and end frame ranges

  audio_ranges = {
      "<audio-file-01>": [(<start-range-value>, <end-range-value>), (<start-range-value>, <end-range-value>), (<start-range-value>, <end-range-value>)],
      "<audio-file-02>": [(<start-range-value>, <end-range-value>), (<start-range-value>, <end-range-value>)],
      "<audio-file-03>": [(<start-range-value>, <end-range-value>)],
  }

  # Find the ontology object for your Audio Region
  audio_ontology_object: Object = project.ontology_structure.get_child_by_title(
      title="<audio-region-name>", type_=Object
  )

  if audio_ontology_object is None:
      raise ValueError("Audio Region ontology object not found.")

  label_rows = project.list_label_rows_v2()

  # Filter label rows not in range
  def filter_label_rows(label_row) -> bool:
      is_valid = label_row.data_title in audio_ranges
      if not is_valid:
          print(f"Skipping label row: {label_row_title} (no predefined ranges)")
      return is_valid

  label_rows = list(filter(filter_label_rows, label_rows))

  # Initialize label rows using bundles
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Loop through each label row and apply updates
  for label_row in label_rows:
      label_row_title = label_row.data_title

      # Apply all ranges as separate objects
      for start, end in audio_ranges.get(label_row_title, []):

          # 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)]),  # Adjust as needed
              frames=0,

              manual_annotation=True,
              confidence=1.0,
          )

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

          print(f"Added range ({start}, {end}) to label row: {label_row_title}")

      # Upload the label to the server after adding all instances
      label_row.save()
      print(f"Saved label row: {label_row_title}")

  print("Updates applied with predefined frame ranges for each data unit!")

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from pathlib import Path

  from encord import EncordUserClient, Project
  from encord.objects import (
      Object,
      ObjectInstance,
  )
  from encord.objects.coordinates import AudioCoordinates
  from encord.objects.frames import Range

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_HASH = "55ee05af-1762-478c-9b3c-d43b4ad39ad4"

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

  # Get the project for which predictions are to be added
  project: Project = user_client.get_project(PROJECT_HASH)

  # Example mapping of data unit titles to start and end frame ranges

  audio_ranges = {
      "my-audio-file.mp3": [(8000, 15000), (20000, 25000), (31000, 43003)],
      "your-audio-file.mp3": [(2500, 4500), (6543, 9876)],
      "their-audio-file.mp3": [(4321, 10987)],
  }

  # Find the ontology object for the Audio Region "Speaking"
  audio_ontology_object: Object = project.ontology_structure.get_child_by_title(
      title="Speaking", type_=Object
  )

  if audio_ontology_object is None:
      raise ValueError("Audio Region ontology object not found.")

  label_rows = project.list_label_rows_v2()

  # Filter label rows not in range
  def filter_label_rows(label_row) -> bool:
      is_valid = label_row.data_title in audio_ranges
      if not is_valid:
          print(f"Skipping label row: {label_row_title} (no predefined ranges)")
      return is_valid

  label_rows = list(filter(filter_label_rows, label_rows))

  # Initialize label rows using bundles
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Loop through each label row and apply updates
  for label_row in label_rows:
      label_row_title = label_row.data_title
      
      # Apply all ranges as separate objects
      for start, end in audio_ranges.get(label_row_title, []):

          # 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)]),  # Adjust as needed
              frames=0,
              manual_annotation=True,
              confidence=1.0,
          )

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

          print(f"Added range ({start}, {end}) to label row: {label_row_title}")

      # Upload the label to the server after adding all instances
      label_row.save()
      print(f"Saved label row: {label_row_title}")

  print("Updates applied with predefined frame ranges for each data unit!")

  ```
</CodeGroup>

## Classifications on Audio Files

### View Classifications on Audio Files

```python theme={"dark"}

# Import dependencies
from encord import EncordUserClient

# Instantiate client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Specify Project
project = user_client.get_project("<project_id>")

# Downloads a local copy of all the labels
label_rows = project.list_label_rows_v2(include_all_label_branches=True) 

# Initialize label rows using bundles
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    print(f"Title: {label_row.data_title}, branch: {label_row.branch_name}")

    # Print all essential classification information
    for classification_instance in label_row.get_classification_instances():
        print(f"classificationHash: {classification_instance.classification_hash}")
        print(f"Classification name: {classification_instance.classification_name}")
        print(f"featureHash: {classification_instance.feature_hash}")
        print(f"Classification answer: {classification_instance.get_answer().value}")
        print(f"Classification answer hash: {classification_instance.get_answer().feature_node_hash}")

```

### Export Classifications from Audio Files

```python Template theme={"dark"}

# Import dependencies
from encord import EncordUserClient
import json

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

PROJECT_ID = "<your-project-id>"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify Project
project = user_client.get_project(PROJECT_ID)

# Downloads a local copy of all the labels
label_rows = project.list_label_rows_v2(include_all_label_branches=True) 

# Initialize label rows using bundles
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    print(f"Title: {label_row.data_title}, branch: {label_row.branch_name}")

    # Export classifications
    classifications = []
    for classification_instance in label_row.get_classification_instances():
        classification_data = {
            "classificationHash": classification_instance.classification_hash,
            "name": classification_instance.classification_name,
            "featureHash": classification_instance.feature_hash,
            "answer": classification_instance.get_answer().value,
            "answerHash": classification_instance.get_answer().feature_node_hash,
        }
        classifications.append(classification_data)
    
    # Print or save the exported classifications
    print(json.dumps(classifications, indent=2))
    # Alternatively, you can save to a file:
    # with open(f"{label_row.data_title}_classifications.json", "w") as f:
    #     json.dump(classifications, f, indent=2)

```

### Import Classifications to Audio Files

<CodeGroup>
  ```python Template theme={"dark"}

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

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

  # Instantiate Encord client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify the project
  project = user_client.get_project(PROJECT_ID)

  # Define a mapping where each file has a list of classifications and options
  file_classification_mapping = {
      "<audio-file-01.file-extension>": [
          {"classification_name": "<classification-name-01>", "option_title": "<option-value>"},
          {"classification_name": "<classification-name-02>", "option_title": "<option-value>"},
      ],
      "<audio-file-02.file-extension>": [
          {"classification_name": "<classification-name-01>", "option_title": "<option-value>"},
      ],
      "<audio-file-03.file-extension>": [
          {"classification_name": "<classification-name-01>", "option_title": "<option-value>"},
      ],
      # Add more mappings as needed
  }

  # Loop through the mapping to apply classifications to each unique file
  for file_name, classifications in file_classification_mapping.items():
      try:
          # Fetch the label row for the given file name
          label_row = project.list_label_rows_v2(data_title_eq=file_name)[0]

          print(label_row.data_hash)

          label_row.initialise_labels()

          for classification_data in classifications:
              # Fetch the classification from the ontology
              ontology_classification: Classification = project.ontology_structure.get_child_by_title(
                  title=classification_data["classification_name"],
                  type_=Classification,
              )

              # Fetch the classification option
              option = ontology_classification.get_child_by_title(
                  title=classification_data["option_title"], type_=Option
              )

              # Create a classification instance
              # range_only=True must be used when creating the classification
              classification_instance = ontology_classification.create_instance(range_only=True)
              classification_instance.set_answer(answer=option)

              # Set classification to apply to frame 0
              classification_instance.set_for_frames(
                  frames=0,
                  manual_annotation=True,
                  confidence=1.0,
              )

              # Add classification instance to the label row
              label_row.add_classification_instance(classification_instance)

          # Save the updated label row after all classifications are added
          label_row.save()

          print(f"Successfully updated classifications for {file_name}.")
      except Exception as e:
          print(f"Failed to update classifications for {file_name}: {e}")

  ```

  ```python Example theme={"dark"}

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

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID = "f60f33cd-213b-400a-b974-7a6a6687a24c"

  # Instantiate Encord client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify the project
  project = user_client.get_project(PROJECT_ID)

  # Define a mapping where each file has a list of classifications and options
  file_classification_mapping = {
      "sh-b-p.mp3": [
          {"classification_name": "Person speaking", "option_title": "Yes"},
          {"classification_name": "Volume", "option_title": "Loud"},
      ],
      "superhero-trailer-110450.mp3": [
          {"classification_name": "Person speaking", "option_title": "No"},
      ],
      "stomping-rock-four-shots-111444.mp3": [
          {"classification_name": "Person speaking", "option_title": "No"},
      ],
      # Add more mappings as needed
  }

  # Loop through the mapping to apply classifications to each unique file
  for file_name, classifications in file_classification_mapping.items():
      try:
          # Fetch the label row for the given file name
          label_row = project.list_label_rows_v2(data_title_eq=file_name)[0]

          print(label_row.data_hash)

          label_row.initialise_labels()

          for classification_data in classifications:
              # Fetch the classification from the ontology
              ontology_classification: Classification = project.ontology_structure.get_child_by_title(
                  title=classification_data["classification_name"],
                  type_=Classification,
              )

              # Fetch the classification option
              option = ontology_classification.get_child_by_title(
                  title=classification_data["option_title"], type_=Option
              )

              # Create a classification instance
              # range_only=True must be used when creating the classification
              classification_instance = ontology_classification.create_instance(range_only=True)
              classification_instance.set_answer(answer=option)

              # Set classification to apply to frame 0
              classification_instance.set_for_frames(
                  frames=0,
                  manual_annotation=True,
                  confidence=1.0,
              )

              # Add classification instance to the label row
              label_row.add_classification_instance(classification_instance)

          # Save the updated label row after all classifications are added
          label_row.save()

          print(f"Successfully updated classifications for {file_name}.")
      except Exception as e:
          print(f"Failed to update classifications for {file_name}: {e}")


  ```
</CodeGroup>


# Data Groups & Label Spaces
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-data-group-labels



Working with Data Group labels requires the use of Label Spaces. Each Data Group's Label Row contains multiple Label Spaces, with each Space corresponding to a specific Data Group item. [Multi-layer Data Groups](/sdk-documentation/index-sdk/sdk-data-groups#multi-layer-data-groups) also contain a root Label Space that contains labels pertaining to the Data Group as a whole.

<Warning>
  **Deprecated (SDK v0.1.195):** The previous approach — fetching a Data Group's **child** label rows directly with `list_label_rows_v2(include_children=True)` and editing each child's labels — is deprecated. Always work on the Data Group **parent** and reach each child through its Label Space using `LabelRowV2.get_spaces()` / `LabelRowV2.get_space(...)`, as shown below. This keeps all labels on the parent, which simplifies `parallel` and `consensus` tasks and improves performance.
</Warning>

## Get Label Spaces

The following script gets all Label Spaces in Label Row and prints their IDs.

```python Get All Label Space IDs theme={"dark"}
from encord import EncordUserClient, Project

# User input
SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 

# --- 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",
)

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

# Get all Label Rows for the data unit
rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
# Assume we want the first Label Row
lr = rows[0]
lr.initialise_labels()

# Get all Label Spaces for the Label Row
label_spaces = lr.get_spaces()

# Print IDs
for space in label_spaces:
    print(
        f"spaceId: {space.space_id}, "
        f"file_name: {space.metadata.file_name}, "
        f"layout_key: {space.metadata.layout_key}"
    )
```

## Get & Update Labels

Use the following scripts to get all annotations in a Label Space. The script shows how annotations can be updated by changing the `last_edited_by` and annotation coordinates for each annotation in the Label Space.

Ensure that you replace:

* All variables in the `User input` section at the top of the script.
* The names of objects in your Ontology.
* The type and position of the label(s).

<Tip>
  Label Spaces can be specified using:

  * A storage item's unique ID: `label_space = lr.get_space(id="7E3KERd9arYTiPicaijP6c1LfI73", type_="image")`
  * Its [Data Group](/sdk-documentation/index-sdk/sdk-data-groups) layout key: `label_space = lr.get_space(layout_key="2", type_="image")`.

  Using `layout_key`s lets you reuse the same code across multiple label rows and Data Groups (for example, "left-video" and "right-video"), without needing to look up the underlying storage item ID each time.
</Tip>

<CodeGroup>
  ```python Image theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects.coordinates import BoundingBoxCoordinates

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

  project: Project = user_client.get_project(PROJECT_ID)

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Replace ID with the unique ID of the Label Space 
  label_space = lr.get_space(id=LABEL_SPACE, type_="image")

  # Get object instances
  object_instances = label_space.get_object_instances()

  # Get annotations
  for annotation in label_space.get_annotations(type_="object"):
  	print(annotation.coordinates)
  	print(annotation.last_edited_by)
  	print(annotation.last_edited_at)
  	print(annotation.confidence)
  	print(annotation.object_hash)
  	print(annotation.space)

  	# Update the annotations
  	annotation.last_edited_by = "user@encord.com"
  	annotation.coordinates = BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.1,
      )

  # Save Label Row
  lr.save()
  ```

  ```python Image Sequence theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects.coordinates import BoundingBoxCoordinates

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

  project: Project = user_client.get_project(PROJECT_ID)

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Replace ID with the unique ID of the Label Space 
  label_space = lr.get_space(id=LABEL_SPACE, type_="image_sequence")

  # Get object instances
  object_instances = label_space.get_object_instances()

  # Get annotations
  for annotation in label_space.get_annotations(type_="object"):
  	print(annotation.coordinates)
  	print(annotation.last_edited_by)
  	print(annotation.last_edited_at)
  	print(annotation.confidence)
  	print(annotation.frame)
  	print(annotation.object_hash)
  	print(annotation.space)

  	# Update the annotations
  	annotation.last_edited_by = "user@encord.com"
  	annotation.coordinates = BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.1,
      )
  # Save Label Row
  lr.save()
  ```

  ```python Video theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects.coordinates import BoundingBoxCoordinates

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

  project: Project = user_client.get_project(PROJECT_ID)

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Replace ID with the unique ID of the Label Space 
  label_space = lr.get_space(id=LABEL_SPACE, type_="video")

  # Get object instances
  object_instances = label_space.get_object_instances()

  # Get annotations
  for annotation in label_space.get_annotations(type_="object"):
  	print(annotation.coordinates)
  	print(annotation.last_edited_by)
  	print(annotation.last_edited_at)
  	print(annotation.confidence)
  	print(annotation.frame)
  	print(annotation.object_hash)
  	print(annotation.space)

  	# Update the annotations
  	annotation.last_edited_by = "user@encord.com"
  	annotation.coordinates = BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.1,
      )

  # Save Label Row
  lr.save()
  ```

  ```python Audio theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Range

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

  project: Project = user_client.get_project(PROJECT_ID)

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Replace ID with the unique ID of the Label Space 
  label_space = lr.get_space(id=LABEL_SPACE, type_="audio")

  # Get object instances
  object_instances = label_space.get_object_instances()

  # Get annotations
  for annotation in label_space.get_annotations(type_="object"):
  	print(annotation.ranges)
  	print(annotation.last_edited_by)
  	print(annotation.last_edited_at)
  	print(annotation.object_hash)
  	print(annotation.space)

  	# Update the annotations
  	annotation.last_edited_by = "user@encord.com"
  	annotation.ranges = Range(start=0, end=100)

  # Save Label Row
  lr.save()
  ```

  ```python Text theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Range

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

  project: Project = user_client.get_project(PROJECT_ID)

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Replace ID with the unique ID of the Label Space 
  label_space = lr.get_space(id=LABEL_SPACE, type_="text")

  # Get object instances
  object_instances = label_space.get_object_instances()

  # Get annotations
  for annotation in label_space.get_annotations(type_="object"):
  	print(annotation.last_edited_by)
  	print(annotation.last_edited_at)
  	print(annotation.object_hash)
  	print(annotation.space)

  	# Update the annotations
  	annotation.last_edited_by = "user@encord.com"
  	annotation.ranges = Range(start=0, end=100)

  # Save Label Row
  lr.save()
  ```

  ```python HTML theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import HtmlRange, HtmlNode

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

  project: Project = user_client.get_project(PROJECT_ID)

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Replace ID with the unique ID of the Label Space 
  label_space = lr.get_space(id=LABEL_SPACE, type_="html")

  # Get object instances
  object_instances = label_space.get_object_instances()

  # Get annotations
  for annotation in label_space.get_annotations(type_="object"):
  	print(annotation.last_edited_by)
  	print(annotation.last_edited_at)
  	print(annotation.object_hash)
  	print(annotation.space)

  	# Update the annotations
  	annotation.last_edited_by = "user@encord.com"
  	annotation.range = HtmlRange(start=HtmlNode(xpath="start", offset=0), end=HtmlNode(xpath="end", offset=1))

  # Save Label Row
  lr.save()
  ```

  ```python PDF theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects.coordinates import BoundingBoxCoordinates

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

  project: Project = user_client.get_project(PROJECT_ID)

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Replace ID with the unique ID of the Label Space 
  label_space = lr.get_space(id=LABEL_SPACE, type_="pdf")

  # Get object instances
  object_instances = label_space.get_object_instances()

  # Get annotations
  for annotation in label_space.get_annotations(type_="object"):
  	print(annotation.coordinates)
  	print(annotation.last_edited_by)
  	print(annotation.last_edited_at)
  	print(annotation.confidence)
  	print(annotation.object_hash)
  	print(annotation.space)

  	# Update the annotations
  	annotation.last_edited_by = "user@encord.com"
  	annotation.coordinates = BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.1,
      )

  # Save Label Row
  lr.save()
  ```

  ```python DICOM / NIfTI theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects.coordinates import BoundingBoxCoordinates

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

  project: Project = user_client.get_project(PROJECT_ID)

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Replace ID with the unique ID of the Label Space 
  label_space = lr.get_space(id=LABEL_SPACE, type_="medical")

  # Get object instances
  object_instances = label_space.get_object_instances()

  # Get annotations
  for annotation in label_space.get_annotations(type_="object"):
  	print(annotation.coordinates)
  	print(annotation.last_edited_by)
  	print(annotation.last_edited_at)
  	print(annotation.confidence)
  	print(annotation.frame)
  	print(annotation.object_hash)
  	print(annotation.space)

  	# Update the annotations
  	annotation.last_edited_by = "user@encord.com"
  	annotation.coordinates = BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.1,
      )

  # Save Label Row
  lr.save()
  ```
</CodeGroup>

## Add Labels

The following scripts add a single object with an attribute, and a classification to two different Label Spaces.

<Info>
  Attributes are set on the object instance itself, so the same attribute values apply across all Label Spaces the instance is added to.
</Info>

Ensure that you replace:

* All variables in the `User input` section at the top of the script.
* The names of objects in your Ontology.
* The type and position of the label(s).

<Tip>
  Use the `on_overlap="replace"` parameter in the `put_classification_instance` and `put_object_instance` methods if you want existing labels to be replaced by the new object.
</Tip>

<CodeGroup>
  ```python Image theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find bounding box object "Cherry" in the Ontology.
  ontology_structure = project.ontology_structure
  box_ontology_object: Object = ontology_structure.get_child_by_title(title="Cherry", type_=Object)

  # Find classification "Day or Night" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Day or Night", type_=Classification)

  # Find classification answer "Day" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Day", type_=Option
  )

  # Get Label Spaces
  label_space_1 = lr.get_space(layout_key="Fruit_1", type_="image")
  label_space_2 = lr.get_space(layout_key="Fruit_2", type_="image")

  # Create bounding box instance
  bb_inst: ObjectInstance = box_ontology_object.create_instance()

  # Find the text attribute "Ripeness description" in the Ontology and set the answer
  attribute = box_ontology_object.get_child_by_title("Ripeness description")
  bb_inst.set_answer(attribute=attribute, answer="Fully ripe, deep red color with no visible blemishes")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()

  classification_inst.set_answer(
      answer=classification_answer
  )

  # Add the bounding box instance to both Label Spaces
  label_space_1.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0, 1, 2]
      )

  label_space_2.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0, 1, 2]
      )

  # Add the classification instance to both Label Spaces
  label_space_1.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0, 1, 2]
  )

  label_space_2.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0, 1, 2]
  )

  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Image Sequence theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find bounding box object "Person" in the Ontology.
  ontology_structure = project.ontology_structure
  box_ontology_object: Object = ontology_structure.get_child_by_title(title="Person", type_=Object)

  # Find classification "Day or Night" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Day or Night", type_=Classification)

  # Find classification answer "Day" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Day", type_=Option
  )

  # Get Label Spaces
  label_space_1 = lr.get_space(layout_key="cctv_1", type_="image_sequence")
  label_space_2 = lr.get_space(layout_key="cctv_2", type_="image_sequence")

  # Create bounding box instance
  bb_inst: ObjectInstance = box_ontology_object.create_instance()

  # Find the text attribute "Visibility description" in the Ontology and set the answer
  attribute = box_ontology_object.get_child_by_title("Visibility description")
  bb_inst.set_answer(attribute=attribute, answer="Face fully visible. Body partially occluded.")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()

  classification_inst.set_answer(
      answer=classification_answer
  )

  # Add the bounding box instance to both Label Spaces 
  label_space_1.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0, 1, 2]
      )

  label_space_2.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0, 1, 2]
      )

  # Add the classification instance to both Label Spaces
  label_space_1.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0, 1, 2]
  )

  label_space_2.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0, 1, 2]
  )

  # Save Label Row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Video theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find bounding box object "Person" in the Ontology.
  ontology_structure = project.ontology_structure
  box_ontology_object: Object = ontology_structure.get_child_by_title(title="Person", type_=Object)

  # Find classification "Day or Night" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Day or Night", type_=Classification)

  # Find classification answer "Day" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Day", type_=Option
  )

  # Get Label Spaces
  label_space_1 = lr.get_space(layout_key="cctv_1", type_="video")
  label_space_2 = lr.get_space(layout_key="cctv_2", type_="video")

  # Create bounding box instance
  bb_inst: ObjectInstance = box_ontology_object.create_instance()

  # Find the text attribute "Visibility description" in the Ontology object and set the answer
  attribute = box_ontology_object.get_child_by_title("Visibility description")
  bb_inst.set_answer(attribute=attribute, answer="Face fully visible. Body partially occluded.")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()

  classification_inst.set_answer(
      answer=classification_answer
  )

  # Add the bounding box instance to both Label Spaces
  label_space_1.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0, 1, 2]
      )

  label_space_2.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0, 1, 2]
      )

  # Add the classification instance to both Label Spaces
  label_space_1.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0, 1, 2]
  )

  label_space_2.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0, 1, 2]
  )

  # Save Label Row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Audio theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2, Range
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find audio region object "Rick James" in the Ontology.
  ontology_structure = project.ontology_structure
  ontology_object: Object = ontology_structure.get_child_by_title(title="Rick James", type_=Object)

  # Find classification "Contains Lyrics?" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Contains Lyrics?", type_=Classification)

  # Find classification answer "Yes" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Yes", type_=Option
  )

  # Get Label Spaces
  label_space = lr.get_space(layout_key="music_1", type_="audio")
  label_space = lr.get_space(layout_key="music_2", type_="audio")

  # Create audio region instance
  audio_inst: ObjectInstance = ontology_object.create_instance()

  # Find the text attribute "Description" in the Ontology object and set the answer
  attribute = ontology_object.get_child_by_title("Description")
  bb_inst.set_answer(attribute=attribute, answer="Very Funky")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()

  # Set classification answer
  classification_inst.set_answer(
      answer=classification_answer
      )

  # Add the audio region instance to both Label Spaces
  label_space_1.put_object_instance(
      object_instance=audio_inst,
      on_overlap="replace",
      ranges=Range(start=100, end=2000)
      )

  label_space_2.put_object_instance(
      object_instance=audio_inst,
      on_overlap="replace",
      ranges=Range(start=100, end=2000)
      )

  # Add the classification instance to both Label Spaces
  label_space_1.put_classification_instance(
      classification_instance=classification_inst
      )

  label_space_2.put_classification_instance(
  classification_instance=classification_inst
  )

  # Save Label Row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Text theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2, Range
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find text region object "Quote" in the Ontology.
  ontology_structure = project.ontology_structure
  ontology_object: Object = ontology_structure.get_child_by_title(title="Quote", type_=Object)

  # Find classification "Easy to Read?" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Easy to Read?", type_=Classification)

  # Find classification answer "Yes" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Yes", type_=Option
  )

  # Get Label Spaces
  label_space_1 = lr.get_space(layout_key="text_1", type_="text")
  label_space_2 = lr.get_space(layout_key="text_2", type_="text")

  # Create text region instance
  text_inst: ObjectInstance = ontology_object.create_instance()

  # Find the text attribute "Author" in the Ontology object and set the answer
  attribute = ontology_object.get_child_by_title("Author")
  bb_inst.set_answer(attribute=attribute, answer="Bertrand Russel")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()

  # Set classification answer
  classification_inst.set_answer(
      answer=classification_answer
  )

  # Add the text region instance to both Label Spaces
  label_space_1.put_object_instance(
      object_instance=text_inst,
      on_overlap="replace",
      ranges=Range(start=100, end=2000)
  )

  label_space_2.put_object_instance(
      object_instance=text_inst,
      on_overlap="replace",
      ranges=Range(start=100, end=2000)
  )

  # Add the classification instance to both Label Spaces
  label_space_1.put_classification_instance(
      classification_instance=classification_inst
  )

  label_space_2.put_classification_instance(
      classification_instance=classification_inst
  )

  # Save Label Row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python HTML theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2, HtmlRange, HtmlNode
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)

  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find text region object "Quote" in the Ontology.
  ontology_structure = project.ontology_structure
  ontology_object: Object = ontology_structure.get_child_by_title(title="Quote", type_=Object)

  # Find classification "Easy to Read?" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Easy to Read?", type_=Classification)

  # Find classification answer "Yes" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Yes", type_=Option
  )

  # Get Label Spaces
  label_space_1 = lr.get_space(layout_key="website_1", type_="html")
  label_space_2 = lr.get_space(layout_key="website_2", type_="html")

  # Create text region instance
  text_inst: ObjectInstance = ontology_object.create_instance()

  # Find the text attribute "Author" in the Ontology object and set the answer
  attribute = ontology_object.get_child_by_title("Author")
  bb_inst.set_answer(attribute=attribute, answer="Bertrand Russel")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()

  # Set classification answer
  classification_inst.set_answer(
      answer=classification_answer
  )

  # Add the text region instance to both Label Spaces
  label_space_1.put_object_instance(
      object_instance=text_inst,
      on_overlap="replace",
      ranges= HtmlRange(start=HtmlNode(xpath="start", offset=0), end=HtmlNode(xpath="end", offset=1))
  )

  label_space_2.put_object_instance(
      object_instance=text_inst,
      on_overlap="replace",
      ranges= HtmlRange(start=HtmlNode(xpath="start", offset=0), end=HtmlNode(xpath="end", offset=1))
  )

  # Add the classification instance to both Label Spaces
  label_space_1.put_classification_instance(
      classification_instance=classification_inst
  )
  label_space_2.put_classification_instance(
      classification_instance=classification_inst
  )

  # Save Label Row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python PDF theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)

  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find bounding box object "Region of Interest" in the Ontology.
  ontology_structure = project.ontology_structure
  box_ontology_object: Object = ontology_structure.get_child_by_title(title="Region of Interest", type_=Object)

  # Find classification "Readable?" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Readable?", type_=Classification)

  # Find classification answer "Yes" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Yes", type_=Option
  )

  # Get Label Spaces
  label_space_1 = lr.get_space(layout_key="doc_1", type_="pdf")
  label_space_2 = lr.get_space(layout_key="doc_2", type_="pdf")

  # Create bounding box instance
  bb_inst: ObjectInstance = box_ontology_object.create_instance()

  # Find the text attribute "Language" in the Ontology object and set the answer
  attribute = box_ontology_object.get_child_by_title("Language")
  bb_inst.set_answer(attribute=attribute, answer="Russian")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()

  # Set classification answer
  classification_inst.set_answer(
      answer=classification_answer
  )

  # Add the bounding box instance to both Label Spaces. Frame refers to page number.
  label_space_1.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0]
  )

  label_space_2.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0]
  )

  # Add the classification instance to both Label Spaces
  label_space_1.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0]
  )

  label_space_2.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0]
  )

  # Save Label Row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python DICOM / NIfTI theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find bounding box object "Region of Interest" in the Ontology.
  ontology_structure = project.ontology_structure
  box_ontology_object: Object = ontology_structure.get_child_by_title(title="Region of Interest", type_=Object)

  # Find classification "Valid Scan?" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Valid Scan?", type_=Classification)

  # Find classification answer "Yes" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Yes", type_=Option
  )

  # Get Label Spaces
  label_space_1 = lr.get_space(layout_key="scan_1", type_="medical")
  label_space_2 = lr.get_space(layout_key="scan_2", type_="medical")

  # Create bounding box instance
  bb_inst: ObjectInstance = box_ontology_object.create_instance()

  # Find the text attribute "Abnormality description" in the Ontology object and set the answer
  attribute = box_ontology_object.get_child_by_title("Abnormality description")
  bb_inst.set_answer(attribute=attribute, answer="Nodule detected, approximately 3mm in diameter")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()

  # Set classification answer
  classification_inst.set_answer(
      answer=classification_answer
  )

  # Add the bounding box instance to both Label Spaces
  label_space_1.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0]
  )

  label_space_2.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0]
  )

  # Add the classification instance to both Label Spaces
  label_space_1.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0]
  )

  label_space_2.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0]
  )

  # Save Label Row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Multi Layer Data Group theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"       # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"           # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>"      # Replace with the title of the data unit

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)

  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # --- Ontology setup ---
  ontology_structure = project.ontology_structure

  # Find bounding box object "Cherry" in the Ontology
  box_ontology_object: Object = ontology_structure.get_child_by_title(title="Cherry", type_=Object)

  # Find classification "Day or Night" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Day or Night", type_=Classification)

  # Find classification answer "Day" in the Ontology
  classification_answer = classification.get_child_by_title(title="Day", type_=Option)

  # --- Get Label Spaces for each image layer in the data group ---
  # Use layout_key to target individual image layers within the data group
  root_space = lr.get_space(id="root", type_="image")                    # Root space: applies to the data group as a whole
  label_space_1 = lr.get_space(layout_key="Fruit_1", type_="image")     # Layer 1
  label_space_2 = lr.get_space(layout_key="Fruit_2", type_="image")     # Layer 2
  label_space_3 = lr.get_space(layout_key="Fruit_3", type_="image")     # Layer 3

  # --- Create instances ---

  # Create bounding box instance
  bb_inst: ObjectInstance = box_ontology_object.create_instance()

  # Set a text attribute answer on the bounding box
  attribute = box_ontology_object.get_child_by_title("Ripeness description")
  bb_inst.set_answer(attribute=attribute, answer="Fully ripe, deep red color with no visible blemishes")

  # Create classification instance and set answer
  classification_inst: ClassificationInstance = classification.create_instance()
  classification_inst.set_answer(answer=classification_answer)

  # --- Add a root-level label that applies to the whole data group ---
  # Adding to root_space applies the classification to the entire data group.
  # No need to add it to individual layer spaces.
  root_space.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0]
  )

  # --- Add bounding box labels to each individual image layer ---
  for space in [label_space_1, label_space_2, label_space_3]:
      space.put_object_instance(
          object_instance=bb_inst,
          on_overlap="replace",
          coordinates=BoundingBoxCoordinates(
              top_left_x=0.6,
              top_left_y=0.4,
              width=0.3,
              height=0.2
          ),
          frames=[0]
      )

  # Save the label row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```
</CodeGroup>

## Remove Labels

The following scripts remove an object from a Label Space.

Ensure that you replace:

* All variables in the `User input` section at the top of the script.
* The names of objects in your Ontology.
* The type and position of the label(s).

<CodeGroup>
  ```python Image theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space
  OBJECT_INSTANCE = "<object_hash>" # Replace with the object hash of the object you want to remove
  CLASSIFICATION_INSTANCE = "<classification_instance>" # Replace with the classification hash of the classification you want to remove

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Get Label Space
  label_space = lr.get_space(layout_key="Fruit", type_="image")

  # Print first object hash in each label space
  label_spaces = lr.get_spaces()

  for space in label_spaces:
      print(space.get_object_instances()[0].object_hash)


  # Remove object
  label_space.remove_object_instance(
  	object_hash=OBJECT_INSTANCE
  )

  # Remove classification
  label_space.remove_classification_instance(
  	classification_hash=CLASSIFICATION_INSTANCE
  )

  # Save label row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Image Sequence theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space
  OBJECT_INSTANCE = "<object_hash>" # Replace with the object hash of the object you want to remove
  CLASSIFICATION_INSTANCE = "<classification_instance>" # Replace with the classification hash of the classification you want to remove

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Get Label Space
  label_space = lr.get_space(layout_key="cctv", type_="image_sequence")

  # Print first object hash in each label space
  label_spaces = lr.get_spaces()

  for space in label_spaces:
      print(space.get_object_instances()[0].object_hash)

  # Remove object
  label_space.remove_object_instance(
  	object_hash=OBJECT_INSTANCE
  )

  # Remove classification
  label_space.remove_classification_instance(
  	classification_hash=CLASSIFICATION_INSTANCE
  )

  # Save label row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Video theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space
  OBJECT_INSTANCE = "<object_hash>" # Replace with the object hash of the object you want to remove
  CLASSIFICATION_INSTANCE = "<classification_instance>" # Replace with the classification hash of the classification you want to remove

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Get Label Space
  label_space = lr.get_space(layout_key="cctv", type_="video")

  # Print first object hash in each label space
  label_spaces = lr.get_spaces()

  for space in label_spaces:
      print(space.get_object_instances()[0].object_hash)

  # Remove object
  label_space.remove_object_instance(
  	object_hash=OBJECT_INSTANCE
  )

  # Remove classification
  label_space.remove_classification_instance(
  	classification_hash=CLASSIFICATION_INSTANCE
  )

  # Save label row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Audio theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space
  OBJECT_INSTANCE = "<object_hash>" # Replace with the object hash of the object you want to remove
  CLASSIFICATION_INSTANCE = "<classification_instance>" # Replace with the classification hash of the classification you want to remove

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Get Label Space
  label_space = lr.get_space(layout_key="mp3", type_="audio")

  # Print first object hash in each label space
  label_spaces = lr.get_spaces()

  for space in label_spaces:
      print(space.get_object_instances()[0].object_hash)

  # Remove object
  label_space.remove_object_instance(
  	object_hash=OBJECT_INSTANCE
  )

  # Remove classification
  label_space.remove_classification_instance(
  	classification_hash=CLASSIFICATION_INSTANCE
  )

  # Save label row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Text theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space
  OBJECT_INSTANCE = "<object_hash>" # Replace with the object hash of the object you want to remove
  CLASSIFICATION_INSTANCE = "<classification_instance>" # Replace with the classification hash of the classification you want to remove

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Get Label Space
  label_space = lr.get_space(layout_key="text", type_="text")

  # Print first object hash in each label space
  label_spaces = lr.get_spaces()

  for space in label_spaces:
      print(space.get_object_instances()[0].object_hash)

  # Remove object
  label_space.remove_object_instance(
  	object_hash=OBJECT_INSTANCE
  )

  # Remove classification
  label_space.remove_classification_instance(
  	classification_hash=CLASSIFICATION_INSTANCE
  )

  # Save label row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python HTML  theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space
  OBJECT_INSTANCE = "<object_hash>" # Replace with the object hash of the object you want to remove
  CLASSIFICATION_INSTANCE = "<classification_instance>" # Replace with the classification hash of the classification you want to remove

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Get Label Space
  label_space = lr.get_space(layout_key="website", type_="html")

  # Print first object hash in each label space
  label_spaces = lr.get_spaces()

  for space in label_spaces:
      print(space.get_object_instances()[0].object_hash)

  # Remove object
  label_space.remove_object_instance(
  	object_hash=OBJECT_INSTANCE
  )

  # Remove classification
  label_space.remove_classification_instance(
  	classification_hash=CLASSIFICATION_INSTANCE
  )

  # Save label row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python DICOM / NIfTI theme={"dark"}
  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>" # Replace with the title of the data unit 
  LABEL_SPACE = "<label_space_id>" # Replace with the unique ID of the label space
  OBJECT_INSTANCE = "<object_hash>" # Replace with the object hash of the object you want to remove
  CLASSIFICATION_INSTANCE = "<classification_instance>" # Replace with the classification hash of the classification you want to remove

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Get Label Space
  label_space = lr.get_space(layout_key="scan", type_="medical")

  # Print first object hash in each label space
  label_spaces = lr.get_spaces()

  for space in label_spaces:
      print(space.get_object_instances()[0].object_hash)

  # Remove object
  label_space.remove_object_instance(
  	object_hash=OBJECT_INSTANCE
  )

  # Remove classification
  label_space.remove_classification_instance(
  	classification_hash=CLASSIFICATION_INSTANCE
  )

  # Save label row
  lr.save()
  print(f"Saved label row for {lr.data_title}")
  ```

  ```python Multi-Layered Labels theme={"dark"}

  from encord import EncordUserClient, Project
  from encord.objects import Object, Classification, ClassificationInstance, ObjectInstance, LabelRowV2
  from encord.objects.coordinates import BoundingBoxCoordinates
  from encord.objects.options import Option

  # User input
  SSH_PATH = "<private_key_path>"  # Replace with the file path to your SSH private key
  PROJECT_ID = "<project_id>"  # Replace with the unique Project ID
  DATA_TITLE = "<data_unit_title>"  # Replace with the title of the data unit

  # --- 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",
  )

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

  # Get all Label Rows for the data unit
  rows = project.list_label_rows_v2(data_title_eq=DATA_TITLE)

  # Assume we want the first Label Row
  lr = rows[0]
  lr.initialise_labels()

  # Find bounding box object "Cherry" in the Ontology
  ontology_structure = project.ontology_structure
  box_ontology_object: Object = ontology_structure.get_child_by_title(title="Cherry", type_=Object)

  # Find classification "Day or Night" in the Ontology
  classification: Classification = ontology_structure.get_child_by_title(title="Day or Night", type_=Classification)

  # Find classification answer "Day" in the Ontology
  classification_answer = classification.get_child_by_title(
      title="Day", type_=Option
  )

  # Get the root Label Space. The root space pertains to the Data Group as a whole, including multi-layered labels
  root_space = lr.get_space(id="root", type_="image")

  # Create bounding box instance
  bb_inst: ObjectInstance = box_ontology_object.create_instance()

  # Find the text attribute "Ripeness description" in the Ontology and set the answer
  attribute = box_ontology_object.get_child_by_title("Ripeness description")
  bb_inst.set_answer(attribute=attribute, answer="Fully ripe, deep red color with no visible blemishes")

  # Create classification instance
  classification_inst: ClassificationInstance = classification.create_instance()
  classification_inst.set_answer(
      answer=classification_answer
  )

  # Add the bounding box instance to the root Label Space
  root_space.put_object_instance(
      object_instance=bb_inst,
      on_overlap="replace",
      coordinates=BoundingBoxCoordinates(
          top_left_x=0.6,
          top_left_y=0.4,
          width=0.3,
          height=0.2
      ),
      frames=[0]
  )

  # Add the classification instance to the root Label Space
  root_space.put_classification_instance(
      classification_instance=classification_inst,
      frames=[0]
  )

  lr.save()
  print(f"Saved label row for {lr.data_title}")

  ```
</CodeGroup>

## Put It All Together

The following is an example demonstrating how to use Label Spaces.

We have Data Groups with five data units in the following layout:

<CodeGroup>
  ```pgsql Data units theme={"dark"}
  +-------------------------------------------+
  |              text file                    |
  +------------------+------------------------+
  |     video 1      |        video 2         |
  +------------------+------------------------+
  |     video 3      |        video 4         |
  +------------------+------------------------+

  ```

  ```pgsql layout_key theme={"dark"}
  +-------------------------------------------+
  |              instructions                 |
  +------------------+------------------------+
  |     top-left     |        top-right       |
  +------------------+------------------------+
  |     bottom-left  |        bottom-left     |
  +------------------+------------------------+
  ```
</CodeGroup>

### Create Example Data Groups

The following script creates the Data Groups and specifies the layout.

```python Create Data Group expandable theme={"dark"}
from uuid import UUID

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupCustom, StorageItemType
from encord.user_client import EncordUserClient

# --- 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)

# --- Reusable layout and settings ---
layout = {
    "direction": "column",
    "first": {"type": "data_unit", "key": "instructions"},
    "second": {
        "direction": "column",
        "first": {
            "direction": "row",
            "first": {"type": "data_unit", "key": "top-left"},
            "second": {"type": "data_unit", "key": "top-right"},
            "splitPercentage": 50,
        },
        "second": {
            "direction": "row",
            "first": {"type": "data_unit", "key": "bottom-left"},
            "second": {"type": "data_unit", "key": "bottom-right"},
            "splitPercentage": 50,
        },
        "splitPercentage": 50,
    },
    "splitPercentage": 20,
}
settings = {"tile_settings": {"instructions": {"is_read_only": True}}}

# --- Group definitions (name + UUIDs) ---
groups = [
    {
        "name": "group-001",
        "uuids": {
            "instructions": UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID of clustered_event_log_01.txt
            "top-left": UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID of 00001_normalized.mp4
            "top-right": UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID of 00002_normalized.mp4
            "bottom-left": UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID of 00009.mp4
            "bottom-right": UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID of 00011_normalized.mp4
        },
    },
    {
        "name": "group-002",
        "uuids": {
            "instructions": UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID of clustered_event_log_02.txt
            "top-left": UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID of 00012.mp4
            "top-right": UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID of 00020.mp4
            "bottom-left": UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID of 00030.mp4
            "bottom-right": UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID of 00033.mp4
        },
    },
    {
        "name": "group-003",
        "uuids": {
            "instructions": UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID of clustered_event_log_03.txt
            "top-left": UUID("23232323-2323-2323-2323-232323232323"), # Replace with File ID of 00034.mp4
            "top-right": UUID("31313131-3131-3131-3131-313131313131"), # Replace with File ID of 00035_normalized.mp4
            "bottom-left": UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID of 00038_normalized.mp4
            "bottom-right": UUID("56565656-6565-5656-6565-656565656565 "), # Replace with File ID of 00045.mp4
        },
    },
    # More groups...
]

# Create the data groups

for g in groups:
    group = folder.create_data_group(
        DataGroupCustom(
            name=g["name"],
            layout=layout,
            layout_contents=g["uuids"],
            settings=settings,
        )
    )
    print(f"✅ Created group '{g['name']}' with UUID {group}")

# Add all the data groups in a folder to a Dataset
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# Add the Dataset with the Data Groups to a Project

p = user_client.get_project(PROJECT_ID)
rows = p.list_label_rows_v2()

# Data Group labels are accessed through the parent row's Label Spaces
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        for space in row.get_spaces():
            print(
                f"space_id: {space.space_id}, "
                f"file_name: {space.metadata.file_name}, "
                f"layout_key: {space.metadata.layout_key}"
            )
```

### Pre-label Data Groups

We want to pre-label the classifications for all videos with the **layout\_key** `top-left` in the Data Groups with **Yes**. This way annotators only need to update the classification for `top-left` videos where there the model predictions and summaries are incorrect.

Our example Project uses a Dataset that contains our Data Groups. The Ontology looks like this:

**Classifications**

* `Prediction correct?`
  * `YES!` (Radio button)
  * `No`  (Radio button)
    * `What's wrong?` (Text)

* `Summary correct?`
  * `YES!` (Radio button)
  * `No`  (Radio button)
    * `What's wrong?` (Text)

![Data Groups Ontology](https://storage.googleapis.com/docs-media.encord.com/E2E%20Artifacts/Screenshots/e2e-data-groups-ontology.png)

```python Import Classification values on top_left videos expandable theme={"dark"}

from __future__ import annotations

from encord import EncordUserClient, Project
from encord.objects import Classification, ClassificationInstance, LabelRowV2
from encord.objects.options import Option


# User input: Edit these values as you require

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


# Only apply to THIS label space
LABEL_SPACE = "top-left"

CLASSIFICATIONS = [
    "Prediction correct?",
    "Summary correct?",
]

ANSWER_TITLE = "YES!"

# Frames to apply the classification to
FRAMES = [0]  # change as needed


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


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

ontology = project.ontology_structure

# Fetch all label rows. Data Group parents are returned directly;
# their children are worked on through each parent's Label Spaces.
all_rows: list[LabelRowV2] = project.list_label_rows_v2()

# Identify Data Group
data_group_parents = [row for row in all_rows if row.group_hash is None]
print(f"Found {len(data_group_parents)} data groups")


# Process each Data Group
for parent in data_group_parents:
    parent.initialise_labels()

    # Helpful: print what spaces actually exist on this group label row
    spaces = parent.get_spaces()
    print(f"Data group '{parent.data_title}' → {len(spaces)} spaces")
    print("  Available layout keys:", [s.metadata.layout_key for s in spaces])

    # Get the target label space from the PARENT row
    try:
        label_space = parent.get_space(layout_key=LABEL_SPACE, type_="video")
    except Exception as e:
        print(f"  ⚠ Could not find space '{LABEL_SPACE}' on group '{parent.data_title}': {e}")
        continue

    for classification_title in CLASSIFICATIONS:
        classification: Classification = ontology.get_child_by_title(
            title=classification_title,
            type_=Classification,
        )

        yes_option: Option = classification.get_child_by_title(
            title=ANSWER_TITLE,
            type_=Option,
        )

        classification_inst: ClassificationInstance = classification.create_instance()
        classification_inst.set_answer(yes_option)

        label_space.put_classification_instance(
            classification_instance=classification_inst
            )

    parent.save()
    print(f"  ✔ Labeled group row: {parent.data_title} (space: {LABEL_SPACE})")

```

## Accessing Storage Item Metadata With Label Spaces

Label spaces provide a direct link to their storage items using the `space_id` property. It maps to the `uuid` of the corresponding `StorageItem`.

<Note>
  `space.space_id` is equivalent to the `uuid` of the storage item. This holds for all label spaces, not just image Data Groups.
</Note>

This means you can use `get_spaces()` on a label row to traverse from a label space to its storage item and access all metadata such as image dimensions. The following example demonstrates this using a Data Group of plain images, fetching the height and width of each image through its label space:

```python Get image dimensions from storage item theme={"dark"}
from encord import EncordUserClient

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

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

project = user_client.get_project(PROJECT_ID)

label_rows = project.list_label_rows_v2()
lr = label_rows[0]  # Replace with your target label row
lr.initialise_labels()

# Fetch all storage items
item_ids = [space.space_id for space in lr.get_spaces()]
items = user_client.get_storage_items(item_ids)

for item in items:
    print(f"Height is {item.height}")
    print(f"Width is {item.width}")
```


# Edit & Delete Labels
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-delete-edit-labels-classifications



## Edit Labels

Editing labels after they have been created involves the following steps:

1. Find the label instance you want to edit.
2. Edit the value for the label.
3. Save the changes.

The script below shows how to update the location of an object's bounding box, and attribute values. Ensure you substitute the following values:

* `<private_key_path>` with the full path to your private key.
* `<project_hash>` with the name of the project you want to update labels in.
* `<file_name>` with the name of the file / data unit you want to edit labels for.
* `<object_name>` with the name of the object.
* `<attribute_name>` with the name of the attribute.
* `<option_name>` with the name of the radio button option of the attribute.

```python theme={"dark"}
# Import dependencies
from typing import List

from encord import EncordUserClient
from encord.objects import LabelRowV2, Object, ObjectInstance, OntologyStructure
from encord.objects.coordinates import BoundingBoxCoordinates

# Instantiate Encord client by replacing <private_key_path> with the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

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

# Specify the label row you want to edit labels for. This example takes the first label row
# Replace the <file_name.mp4> with the name of the file you want to change labels for
first_label_row = project.list_label_rows_v2(
    data_title_eq="<file_name>"
)[0]

# Download the existing labels 
first_label_row.initialise_labels()

# Get the first object instance in the label row
ontology_structure = first_label_row.ontology_structure

# Gets the object instance we want to edit the label for. This example uses the first
first_obj_instance = first_label_row.get_object_instances()[0]

# Specifies which Ontology object to change labels for
# Replace <object_name> with the name of your object. For example 'Flower'
my_object = ontology_structure.get_child_by_title(title="<object_name>")

# Sets coordinates for the specified object instance
# This example changes the location of a bounding box
first_obj_instance.set_for_frames(
    coordinates = BoundingBoxCoordinates(
        height=0.1474,
        width =0.1154,
        top_left_x=0.1097,
        top_left_y=0.3209
    ),
    # Overwrites if annotations are already present
    manual_annotation=False, overwrite=True
)

# Selects a Radio button attribute
# Replace <attribute_name> with the name of the attribute you want to edit. For example 'Flower species'
my_attribute = my_object.get_child_by_title(title="<attribute_name>", type_=RadioAttribute)

# Selects the radio button option of the attribute
# Replace <option_name> with the name of the option. For example 'Sunflower' 
attribute_option = my_attribute.get_child_by_title(title="<option_name>", type_= Option)

# Sets the attribute to the attribute_option defined above
first_object_instance.set_answer(attribute_option, overwrite=True)

# Once you have updated labels and attributes, save your changes
first_label_row.save()
```

***

## Delete Labels/Classifications

The following code deletes specific labels/classifications from data units.

<CodeGroup>
  ```python Labels theme={"dark"}

  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "41397c50-d4d5-4c73-bf5d-cb2f72c0dc31"
  DATA_UNIT_NAME = "cherry-002.jpg"

  # Instantiate client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      # If you use the US Encord platform, change domain to https://api.us.encord.com
      domain="https://api.encord.com",
  )

  # Specify Project
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to modify labels for
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]

  # Find the object to remove
  object_to_remove = None
  specific_label_row.initialise_labels()
  for object_instance in specific_label_row.get_object_instances():
      # Specify the label ID for the label to remove
      if object_instance.object_hash == '0pw0bHXR':
          object_to_remove = object_instance

  # Remove the object
  specific_label_row.remove_object(object_to_remove)

  # Save the changes
  specific_label_row.save()

  ```

  ```python Classifications theme={"dark"}

  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "41397c50-d4d5-4c73-bf5d-cb2f72c0dc31"
  DATA_UNIT_NAME = "cherry-002.jpg"

  # Instantiate client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      # If you use the US Encord platform, change domain to https://api.us.encord.com
      domain="https://api.encord.com",
  )

  # Specify Project
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to modify labels for
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]

  # Find the classification to remove
  classification_to_remove = None
  specific_label_row.initialise_labels()
  for classification_instance in specific_label_row.get_classification_instances():
      # Specify the classification ID for the classification to remove
      if classification_instance.classification_hash == '0pw0bHXR':
          classification_to_remove = classification_instance

  # Remove the object
  specific_label_row.remove_classification(classification_to_remove)

  # Save the changes
  specific_label_row.save()

  ```
</CodeGroup>

## Delete All Labels/Classifications

The following code deletes all labels/classifications from the specified data unit.

<CodeGroup>
  ```python Labels theme={"dark"}

  from encord import EncordUserClient

  # Authentication
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "41397c50-d4d5-4c73-bf5d-cb2f72c0dc31"

  # Authenticate
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      # If you use the US Encord platform, change domain to https://api.us.encord.com
      domain="https://api.encord.com",
      )

  # Get Project
  project = Project = user_client.get_project(PROJECT_ID)

  # Get label rows
  label_rows = project.list_label_rows_v2()
  BUNDLE_SIZE = 100

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Delete all objects from specific images
  for label_row in label_rows:
      # Check if this is an image you want to modify
      if label_row.data_title in ["cherry-002.jpg"]:  # Replace with your image names
          # Get all object instances
          objects_to_remove = label_row.get_object_instances()
          # Remove all objects
          for obj in objects_to_remove:
              label_row.remove_object(obj)

  # Save changes using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.save(bundle=bundle)

  ```

  ```python Classifications theme={"dark"}

  from encord import EncordUserClient

  # Authentication
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "41397c50-d4d5-4c73-bf5d-cb2f72c0dc31"

  # Authenticate
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      # If you use the US Encord platform, change domain to https://api.us.encord.com
      domain="https://api.encord.com",
      )

  # Get Project
  project = Project = user_client.get_project(PROJECT_ID)

  # Get label rows
  label_rows = project.list_label_rows_v2()
  BUNDLE_SIZE = 100

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Delete all objects from specific images
  for label_row in label_rows:
      # Check if this is an image you want to modify
      if label_row.data_title in ["cherry-002.jpg"]:  # Replace with your image names
          # Get all object instances
          classifications_to_remove = label_row.get_classification_instances()
          # Remove all objects
          for clas in classifications_to_remove:
              label_row.remove_classification(clas)

  # Save changes using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.save(bundle=bundle)

  ```
</CodeGroup>

## Delete All Specific Labels/Classifications

The following code removes all labels/classifications of a specific type from data units.

<CodeGroup>
  ```python Labels theme={"dark"}

  from encord import EncordUserClient
  from encord.objects import Object

  # Authentication
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "41397c50-d4d5-4c73-bf5d-cb2f72c0dc31"
  TARGET_CLASS_NAME = "Keypoint"
  DATA_UNIT_NAME = "cherry-002.jpg"

  # Authenticate
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      # If you use the US Encord platform, change domain to https://api.us.encord.com
      domain="https://api.encord.com",
  )

  # Get the project
  project = user_client.get_project(PROJECT_ID)

  # Get all label rows in the project
  label_rows = project.list_label_rows_v2()

  BUNDLE_SIZE = 100

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Retrieve the ontology object matching the target class name
  ontology_object = project.ontology_structure.get_child_by_title(
      title=TARGET_CLASS_NAME,
      type_=Object
  )

  # Loop through the label rows and delete only the object instances matching the ontology object
  for label_row in label_rows:
      if label_row.data_title == DATA_UNIT_NAME:
          
          # This returns only the instances of the specific ontology object
          objects_to_remove = label_row.get_object_instances(
              filter_ontology_object=ontology_object
          )

          print(f"Found {len(objects_to_remove)} '{TARGET_CLASS_NAME}' objects in '{DATA_UNIT_NAME}'")

          # Remove those objects
          for obj in objects_to_remove:
              label_row.remove_object(obj)

  # Save changes using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.save(bundle=bundle)

  print(f"Finished! Removed all '{TARGET_CLASS_NAME}' objects from '{DATA_UNIT_NAME}'.")


  ```

  ```python Classifications theme={"dark"}

  from encord import EncordUserClient
  from encord.objects import Classification

  # Authentication
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "41397c50-d4d5-4c73-bf5d-cb2f72c0dc31"
  TARGET_CLASS_NAME = "Classification 2"
  DATA_UNIT_NAME = "cherry-002.jpg"

  # Authenticate
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      # If you use the US Encord platform, change domain to https://api.us.encord.com
      domain="https://api.encord.com",
  )

  # Get the project
  project = user_client.get_project(PROJECT_ID)

  # Get all label rows in the project
  label_rows = project.list_label_rows_v2()

  BUNDLE_SIZE = 100

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Retrieve the ontology object matching the target class name
  ontology_classification = project.ontology_structure.get_child_by_title(
      title=TARGET_CLASS_NAME,
      type_=Classification
  )

  # Loop through the label rows and delete only the classification instances matching the ontology classification
  for label_row in label_rows:
      if label_row.data_title == DATA_UNIT_NAME:
          # This returns only the instances of the specific ontology object
          classifications_to_remove = label_row.get_classification_instances(
              filter_ontology_classification=ontology_classification
          )

          print(f"Found {len(classifications_to_remove)} '{TARGET_CLASS_NAME}' classifications in '{DATA_UNIT_NAME}'")

          # Remove those classifications
          for clas in classifications_to_remove:
              label_row.remove_classification(clas)

  # Save changes using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.save(bundle=bundle)

  print(f"Finished! Removed all '{TARGET_CLASS_NAME}' classifications from '{DATA_UNIT_NAME}'.")

  ```
</CodeGroup>


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



The Encord SDK is designed to offer a versatile and targeted approach to accessing label information. This approach allows for a more customized handling of label information, catering to various needs and scenarios in data processing.

The following table describes all values exported by the scripts on this page.

| Key                          | Description                                                                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| objectHash                   | The unique ID of the object instance. Two instances of the same object have different object hashes                                |
| Object name                  | The name of the object as defined in the Ontology. For example "Chicken".                                                          |
| featureHash                  | The unique ID of the Ontology element. For example, the object "Chicken" in the Ontology. All instances have the same featureHash. |
| uid                          | The unique identifier for the object instance. Two instances of the same object have different uids.                               |
| Object color                 | The color used to label the object, as defined in the Ontology and seen in the Encord platform.                                    |
| Ontology shape               | The shape used to label the object, as defined in the Ontology. For example, polygon.                                              |
| Classification name          | The name of the Classification, as defined in the Ontology. For example "Day or night?"                                            |
| Classification answer        | The value of the Classification, as defined in the Ontology. For example "Day"                                                     |
| classificationHash           | The unique identifier for the Classification instance.                                                                             |
| Classification answer hash   | The unique identifier for the Classification value                                                                                 |
| Attribute name               | The name of the attribute, as defined in the Ontology. For example "Standing or sitting?"                                          |
| Attribute answer             | The name of the attribute value, as defined in the Ontology. For example "Sitting"                                                 |
| Attribute answer featureHash | The unique identifier for the attribute value.                                                                                     |

***

## Export Labels as JSON

The following script prints a JSON file containing all the labels in your Project.

<Note>
  * Adding `include_all_label_branches=True` to `list_label_rows_v2()` includes all labels from all branches in Consensus Projects.
</Note>

<Warning>
  **Deprecated (SDK v0.1.195):** For Data Groups, passing `include_children=True` to `list_label_rows_v2()` to fetch child labels is deprecated. Work on the Data Group **parent** instead and access each child through its Label Space with [`LabelRowV2.get_spaces()`](/sdk-documentation/sdk-labels/sdk-data-group-labels#get-label-spaces).
</Warning>

<Tip>
  We recommend using [`bundle`](/sdk-documentation/sdk-references/http.bundle#bundle-objects) in your scripts to improve performance. Keep bundle sizes under 1000 operations. Bundles of more than 1000 operations can degrade performance rather than improve performance.

  The optimal bundle size depends on your use case. For example, for videos with a large number of labels, start with 20 operations and adjust up or down based on performance.
</Tip>

```python Export labels to JSON expandable theme={"dark"}

# Import dependencies
import json
import os

from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with Project unique ID
BUNDLE_SIZE = 100  # Customize as needed
OUTPUT_JSON = "/Users/chris-encord/export-label-rows.json" # Replace with file path to save JSON output file

# 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",
)

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

# Get label rows for your Project
label_rows = project.list_label_rows_v2()
assert label_rows, f"No label rows found in project {PROJECT_ID}"

# Initialize label rows using bundles
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

# Collect all label row data
all_label_rows = [label_row.to_encord_dict() for label_row in label_rows]
assert all_label_rows, "No label row data collected for export"

# Save the collected label rows data to a JSON file
output_file = OUTPUT_JSON
assert output_file.endswith(".json"), "Output file must be a .json file"

with open(output_file, "w") as file:
    json.dump(all_label_rows, file, indent=4)

print(f"Label rows have been saved to {output_file}.")

```

***

## Export Attributes

The following scripts get the attributes for all labels in a Project, as well as the frames that the attributes appear on. Single images only have a single frame.

<Info>
  We recommend using the script for exporting all attributes if the Project uses
  an Ontology with nested attributes.
</Info>

<CodeGroup>
  ```python Text attributes expandable theme={"dark"}

  # Import dependencies
  import json

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

  # User input
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"
  DATA_UNIT = "cherries-is"
  OUTPUT_FILE_PATH = "/Users/chris-encord/text_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",
  )

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

  # Filter label rows for a specific data title
  label_rows = project.list_label_rows_v2(data_title_eq=DATA_UNIT)
  assert label_rows, f"No label rows found for data title '{DATA_UNIT}'"

  # Initialize labels using bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)


  # Function to extract text attributes and store in structured format
  def extract_text_attributes(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
      if isinstance(attribute, TextAttribute):
          text_answer = object_instance.get_answer(attribute)
          return {
              "frame": frame_number + 1,
              "attribute_name": attribute.title,
              "attribute_hash": attribute.feature_node_hash,
              "text_answer": text_answer,
          }
      return None


  # Collect results for saving
  results = []

  # Iterate through all object instances and collect text attribute data
  for label_row in label_rows:
      object_instances = label_row.get_object_instances()
      assert object_instances, f"No object instances found in label row {label_row.uid}"

      for object_instance in object_instances:
          annotations = object_instance.get_annotations()
          assert annotations, f"No annotations found for object instance {object_instance.object_hash}"

          ontology_item = object_instance.ontology_item
          assert ontology_item and ontology_item.attributes, (
              f"Missing ontology item or attributes for object {object_instance.object_hash}"
          )

          for annotation in annotations:
              for attribute in ontology_item.attributes:
                  attr_data = extract_text_attributes(attribute, object_instance, annotation.frame)
                  if attr_data:
                      results.append(attr_data)
                      # Optional: also print to console
                      print(f"Frame {attr_data['frame']}:")
                      print(f"Text Attribute name: {attr_data['attribute_name']}")
                      print(f"Text Attribute hash: {attr_data['attribute_hash']}")
                      print(f"Text Attribute Answer: {attr_data['text_answer']}")

  # Save results to JSON
  assert OUTPUT_FILE_PATH.endswith(".json"), "Output file path must end with .json"

  with open(OUTPUT_FILE_PATH, "w") as f:
      json.dump(results, f, indent=4)

  print(f"\nText attribute data saved to: {OUTPUT_FILE_PATH}")

  ```

  ```python Radio buttons expandable theme={"dark"}

  # Import dependencies
  import json
  import os

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

  # User input
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"
  DATA_UNIT = "cherries-010.jpg"
  OUTPUT_FILE_PATH = "/Users/chris-encord/radio_attribute_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",
  )

  # Get 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}"

  # Initialize label rows using bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Prepare data structure to collect all results
  output_data = []


  # Function to extract info from RadioAttribute (recursively if nested)
  def extract_attributes(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
      frame_data = []

      if isinstance(attribute, RadioAttribute):
          attribute_answers = object_instance.get_answer(attribute)
          if not isinstance(attribute_answers, list):
              attribute_answers = [attribute_answers]

          for answer in attribute_answers:
              if answer is None:
                  continue  # Skip empty answers

              answer_data = {
                  "frame": frame_number + 1,
                  "attribute_name": attribute.title,
                  "attribute_hash": attribute.feature_node_hash,
                  "answer_title": answer.title,
                  "answer_hash": answer.feature_node_hash,
                  "nested_attributes": [],
              }

              if hasattr(answer, "attributes") and answer.attributes:
                  for nested_attribute in answer.attributes:
                      nested_data = extract_attributes(nested_attribute, object_instance, frame_number)
                      if nested_data:
                          answer_data["nested_attributes"].extend(nested_data)

              frame_data.append(answer_data)

      return frame_data


  # Loop through label rows and extract attribute data
  for label_row in label_rows:
      object_instances = label_row.get_object_instances()
      assert object_instances, f"No object instances found in label row {label_row.uid}"

      for object_instance in object_instances:
          annotations = object_instance.get_annotations()
          assert annotations, f"No annotations found for object instance {object_instance.object_hash}"

          ontology_item = object_instance.ontology_item
          assert ontology_item and ontology_item.attributes, (
              f"No ontology item or attributes found for object {object_instance.object_hash}"
          )

          for annotation in annotations:
              for attribute in ontology_item.attributes:
                  attr_data = extract_attributes(attribute, object_instance, annotation.frame)
                  if attr_data:
                      output_data.extend(attr_data)

  # Save results to JSON
  assert OUTPUT_FILE_PATH.endswith(".json"), "Output file path must end with .json"

  with open(OUTPUT_FILE_PATH, "w") as f:
      json.dump(output_data, f, indent=4)

  print(f"Radio attribute data saved to {OUTPUT_FILE_PATH}")

  ```

  ```python Checklist attributes expandable theme={"dark"}

  # Import dependencies
  import json
  import os

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

  # User input
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"
  DATA_UNIT = "cherries-010.jpg"
  OUTPUT_FILE_PATH = "/Users/chris-encord/checklist_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 the project and filter 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}"

  # Initialize label rows using bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)


  # Function to extract checklist attributes in structured format
  def extract_attributes(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
      if isinstance(attribute, ChecklistAttribute):
          attribute_answers = object_instance.get_answer(attribute)
          if not isinstance(attribute_answers, list):
              attribute_answers = [attribute_answers]

          return {
              "frame": frame_number + 1,
              "attribute_name": attribute.title,
              "attribute_hash": attribute.feature_node_hash,
              "answers": [
                  {
                      "title": answer.title,
                      "hash": answer.feature_node_hash,
                  }
                  for answer in attribute_answers
                  if answer
              ],
          }
      return None


  # Collect data for saving
  results = []

  # Iterate through label rows and extract checklist attribute data
  for label_row in label_rows:
      object_instances = label_row.get_object_instances()
      assert object_instances, f"No object instances found in label row {label_row.uid}"

      for object_instance in object_instances:
          annotations = object_instance.get_annotations()
          assert annotations, f"No annotations found for object instance {object_instance.object_hash}"

          ontology_item = object_instance.ontology_item
          assert ontology_item and ontology_item.attributes, (
              f"No ontology item or attributes found for object {object_instance.object_hash}"
          )

          for annotation in annotations:
              for attribute in ontology_item.attributes:
                  attr_data = extract_attributes(attribute, object_instance, annotation.frame)
                  if attr_data:
                      results.append(attr_data)
                      print(f"Frame {attr_data['frame']}:")
                      print(f"Checklist Attribute name: {attr_data['attribute_name']}")
                      for answer in attr_data["answers"]:
                          print(f"Checklist answer: {answer['title']}")
                          print(f"Checklist answer hash: {answer['hash']}")

  # Save to JSON
  assert OUTPUT_FILE_PATH.endswith(".json"), "Output file path must end with .json"

  with open(OUTPUT_FILE_PATH, "w") as f:
      json.dump(results, f, indent=4)

  print(f"\nChecklist attribute data saved to: {OUTPUT_FILE_PATH}")

  ```

  ```python All attributes theme={"dark"}

  # 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}"

  # Initialize label rows using bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Container for structured results
  results = []


  # Function to collect and print attributes
  def extract_and_print_attributes(attribute: Attribute, object_instance: ObjectInstance, frame_number: int):
      attr_data = {
          "frame": frame_number + 1,
          "attribute_name": attribute.title,
          "attribute_hash": attribute.feature_node_hash,
          "attribute_type": None,
          "answers": [],
      }

      if isinstance(attribute, TextAttribute):
          attr_data["attribute_type"] = "TextAttribute"
          text_answer = object_instance.get_answer(attribute)
          attr_data["answers"].append({"text": text_answer or "No attribute answer"})

      elif isinstance(attribute, RadioAttribute):
          attr_data["attribute_type"] = "RadioAttribute"
          answer = object_instance.get_answer(attribute)
          if answer:
              answer_data = {"title": answer.title, "hash": answer.feature_node_hash, "nested_attributes": []}

              if hasattr(answer, "attributes") and answer.attributes:
                  for nested_attribute in answer.attributes:
                      nested_result = extract_and_print_attributes(nested_attribute, object_instance, frame_number)
                      if nested_result:
                          answer_data["nested_attributes"].append(nested_result)

              attr_data["answers"].append(answer_data)
          else:
              attr_data["answers"].append({"note": "No attribute answer"})

      elif isinstance(attribute, ChecklistAttribute):
          attr_data["attribute_type"] = "ChecklistAttribute"
          answers = object_instance.get_answer(attribute)
          if answers:
              if not isinstance(answers, Iterable):
                  answers = [answers]
              for answer in answers:
                  attr_data["answers"].append({"title": answer.title, "hash": answer.feature_node_hash})
          else:
              attr_data["answers"].append({"note": "No attribute answer"})

      # Print the same info (optional)
      print(f"Frame {attr_data['frame']}: {attr_data['attribute_type']} name: {attr_data['attribute_name']}")
      for answer in attr_data["answers"]:
          if "title" in answer:
              print(f"Answer: {answer['title']}")
              print(f"Answer hash: {answer['hash']}")
          elif "text" in answer:
              print(f"Answer: {answer['text']}")
          elif "note" in answer:
              print(f"Note: {answer['note']}")
          if "nested_attributes" in answer:
              for nested in answer["nested_attributes"]:
                  print(f"Nested attribute: {nested['attribute_name']} ({nested['attribute_hash']})")

      return attr_data


  # Process all label rows
  for label_row in label_rows:
      object_instances = label_row.get_object_instances()
      assert object_instances, f"No object instances found in label row {label_row.uid}"

      for object_instance in object_instances:
          annotations = object_instance.get_annotations()
          assert annotations, f"No annotations found for object instance {object_instance.object_hash}"

          assert object_instance.ontology_item and object_instance.ontology_item.attributes, (
              f"No attributes found for object {object_instance.object_hash}"
          )

          for annotation in annotations:
              for attribute in object_instance.ontology_item.attributes:
                  extracted = extract_and_print_attributes(attribute, object_instance, annotation.frame)
                  if extracted:
                      results.append(extracted)

  # Save to JSON
  assert OUTPUT_FILE_PATH.endswith(".json"), "Output file path must be a JSON file"

  with open(OUTPUT_FILE_PATH, "w") as f:
      json.dump(results, f, indent=4)

  print(f"\nAll attribute data saved to: {OUTPUT_FILE_PATH}")

  ```
</CodeGroup>

***

## Export Objects and Classifications

<Warning>
  The following scripts do not support Ontologies with text classifications, or
  nested classifications. The scripts serve as a template for exporting object
  labels only.
</Warning>

The following script shows how to access and print essential label information for all object and classification instances, and all attributes in a Project. The example for videos, image groups, image sequences and DICOM outputs the frame numbers of each object, classification and attribute.

Make sure you substitute:

* The `<private_key_path>` with the full path to your private key.
* The `<project_id>` with the ID of your Project.

<CodeGroup>
  ```python Videos / Image Groups / Image sequences / DICOM theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.objects.ontology_element import OntologyElement
  from encord.objects.attributes import Attribute
  from encord.objects import ObjectInstance

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Replace <project_id> with the hash of your Project
  project = user_client.get_project("<project_id>")

  # A function to extract and print essential information for all attributes
  def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
      print(f"Attribute name: {attribute.title}")
      print(f"Attribute hash: {attribute.feature_node_hash}")
      for answer_for_frames in object_instance.get_answer(attribute):
          print(f"Attribute answer \"{answer_for_frames.answer.title}\" is present on frames {answer_for_frames.ranges}")
          print ("Attribute answer hash " + answer_for_frames.answer.feature_node_hash)
          for attribute in answer_for_frames.answer.attributes:
              print(f"Attribute answer \"{answer_for_frames.answer.title}\" has nested attribute \"{attribute.title}\"")
              print_attributes(attribute, object_instance)

  # Initialize label rows using bundles
  label_rows = project.list_label_rows_v2()
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  for label_row in label_rows:
      # Print essential label information for all objects
      for object_instance in label_row.get_object_instances():
          print ("objectHash: " + object_instance.object_hash)
          print ("Object name: " + object_instance.object_name)
          print ("featureHash: " + object_instance.feature_hash)
          print ("uid: " + str(object_instance.ontology_item.uid))
          print ("Object color: " + object_instance.ontology_item.color)
          print ("Ontology shape: " + object_instance.ontology_item.shape)

          # Print the frame number and the location of the object on the frame
          for annotation in object_instance.get_annotations():
              print(f"Frame {annotation.frame} -> {annotation.coordinates}")

          # Print all attributes
          for attribute in object_instance.ontology_item.attributes:
              print_attributes(attribute, object_instance)

      # Print all essential classification information
      for classification_instance in label_row.get_classification_instances():
          print ("classificationHash: " + classification_instance.classification_hash)
          print ("Classification name: " + classification_instance.classification_name)
          print ("featureHash: " + classification_instance.feature_hash)
          print ("Classification answer: " + classification_instance.get_answer().value)
          print ("Classification answer hash: " + classification_instance.get_answer().feature_node_hash)

          # Print the frame number(s) that a classification appears on
          for annotation in classification_instance.get_annotations():
              print("Classification appears on frame " + str(annotation.frame))
  ```

  ```python Single images theme={"dark"}
  from encord import EncordUserClient
  from encord.objects.ontology_element import OntologyElement
  from encord.objects.attributes import Attribute
  from encord.objects import ObjectInstance

  # Instantiate Encord client by substituting the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Replace <project_id> with the ID of your Project
  project = user_client.get_project("<project_id>")

  # Print essential info for all attributes
  def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
      print(f"Attribute name: {attribute.title}")
      print(f"Attribute hash: {attribute.feature_node_hash}")
      for attribute_answer in object_instance.get_answer(attribute):
          print(f"Attribute answer: {attribute_answer.answer.title}")
          print ("Attribute answer hash " + attribute_answer.answer.feature_node_hash)
          for attribute in attribute_answer.answer.attributes:
              print(f"Attribute answer \"{attribute_answer.answer.title}\" has nested attribute \"{attribute.title}\"")
              print ("Attribute answer hash " + attribute_answer.answer.feature_node_hash)
              print_attributes(attribute, object_instance)

  # Initialize label rows using bundles
  label_rows = project.list_label_rows_v2()
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  for label_row in label_rows:
      # Print essential label information for all objects
      for object_instance in label_row.get_object_instances():
          print ("objectHash: " + object_instance.object_hash)
          print ("Object name: " + object_instance.object_name)
          print ("featureHash: " + object_instance.feature_hash)
          print ("uid: " + str(object_instance.ontology_item.uid))
          print ("Object color: " + object_instance.ontology_item.color)
          print ("Ontology shape: " + object_instance.ontology_item.shape)

          for annotation in object_instance.get_annotations():
              print(f"Frame {annotation.frame} -> {annotation.coordinates}")

          for attribute in object_instance.ontology_item.attributes:
              print_attributes(attribute, object_instance)

      for classification_instance in label_row.get_classification_instances():
          print ("classificationHash: " + classification_instance.classification_hash)
          print ("Classification name: " + classification_instance.classification_name)
          print ("featureHash: " + classification_instance.feature_hash)

          for annotation in classification_instance.get_annotations():
              print("Classification on frame " + str(annotation.frame))

  ```

  ```python Example Output theme={"dark"}
  objectHash: HI5408US
  Object name: Chicken
  featureHash: p6T5NeQ4
  uid: 1
  Object color: #D33115
  Ontology Shape: bounding_box
  Frame 101 -> BoundingBoxCoordinates(height=0.526, width=0.2514, top_left_x=0.5826, top_left_y=0.2431)
  Frame 102 -> BoundingBoxCoordinates(height=0.5365, width=0.256, top_left_x=0.578, top_left_y=0.2413)
  Frame 103 -> BoundingBoxCoordinates(height=0.5469, width=0.2615, top_left_x=0.5752, top_left_y=0.2378)
  Frame 104 -> BoundingBoxCoordinates(height=0.5365, width=0.256, top_left_x=0.5798, top_left_y=0.2396)
  Frame 105 -> BoundingBoxCoordinates(height=0.5365, width=0.256, top_left_x=0.5661, top_left_y=0.2396)
  Frame 106 -> BoundingBoxCoordinates(height=0.5469, width=0.2615, top_left_x=0.5633, top_left_y=0.2361)
  Frame 107 -> BoundingBoxCoordinates(height=0.5365, width=0.256, top_left_x=0.5532, top_left_y=0.2361)
  Frame 108 -> BoundingBoxCoordinates(height=0.526, width=0.2514, top_left_x=0.556, top_left_y=0.2413)
  Attribute name: Walking or Sitting?
  featureHash: pHXXPbuc
  Attribute answer "Walking" is present on frames [(101:104)]
  Attribute answer featureHash: 6qeufh3l
  Attribute answer "Sitting" is present on frames [(105:108)]
  Attribute answer featureHash: hkInN4Sd
  classificationHash: gffOkg9l
  Classification name: Day or Night?
  featureHash: FA6pAde3
  Classification answer: Day
  Classification answer hash: gasjasd
  Classification appears on frame 352
  ```
</CodeGroup>

## Export Objects, Classifications, and Attributes by Frame

<Warning>
  Videos with [variable frame
  rates](/platform-documentation/General/general-supported-data#frame-synchronization-issues)
  can result in misplaced labels.
</Warning>

### Range of Consecutive Frames

The following scripts download and print the labels for a specified range of frames in videos.

<Tip>To export labels for a single frame, make the \<start\_frame\_number> the same as the \<end\_frame\_number>. For example, to export labels on the 13th frame set \<start\_frame\_number>  = 13, and \<end\_frame\_number> = 13.</Tip>

<CodeGroup>
  ```python Frame range for a specific task expandable theme={"dark"}

  # Import dependencies
  import json

  from encord import EncordUserClient
  from encord.objects import ObjectInstance
  from encord.objects.attributes import Attribute

  # User input
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"
  DATA_UNIT = "cherries-is"
  OUTPUT_FILE_PATH = "/Users/chris-encord/frame_range_output.json"
  START_FRAME_NUMBER = 0
  END_FRAME_NUMBER = 35
  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 the project
  project = user_client.get_project(PROJECT_ID)
  assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"

  # Get filtered label rows
  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}"

  # Initialize labels using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)


  # Function to extract attributes in a structured format
  def extract_attributes(attribute: Attribute, object_instance: ObjectInstance):
      try:
          answer = object_instance.get_answer(attribute)
      except Exception:
          answer = None
      return {
          "attribute_name": attribute.title,
          "attribute_hash": attribute.feature_node_hash,
          "attribute_answer": str(answer),
      }


  # Result collection
  results = []

  # Loop over label rows
  for label_row in label_rows:
      row_data = {
          "label_row_hash": label_row.label_hash,
          "data_title": label_row.data_title,
          "objects": [],
          "classifications": [],
      }

      # Process object annotations
      object_instances = label_row.get_object_instances()
      assert object_instances, f"No object instances found in label row {label_row.uid}"

      for object_instance in object_instances:
          annotations = object_instance.get_annotations()
          assert annotations, f"No annotations found for object instance {object_instance.object_hash}"

          assert object_instance.ontology_item and object_instance.ontology_item.attributes, (
              f"No attributes found for object {object_instance.object_hash}"
          )

          for annotation in annotations:
              if START_FRAME_NUMBER <= annotation.frame <= END_FRAME_NUMBER:
                  obj_info = {
                      "frame": annotation.frame,
                      "object_hash": object_instance.object_hash,
                      "object_name": object_instance.object_name,
                      "feature_hash": object_instance.feature_hash,
                      "uid": str(object_instance.ontology_item.uid),
                      "color": object_instance.ontology_item.color,
                      "shape": object_instance.ontology_item.shape,
                      "label_location": str(annotation.coordinates),
                      "attributes": [],
                  }

                  print("Frame:", annotation.frame)
                  print("objectHash:", object_instance.object_hash)
                  print("Object name:", object_instance.object_name)
                  print("featureHash:", object_instance.feature_hash)
                  print("uid:", obj_info["uid"])
                  print("Object color:", object_instance.ontology_item.color)
                  print("Ontology shape:", object_instance.ontology_item.shape)
                  print(f"Label location: {annotation.coordinates}")

                  for attribute in object_instance.ontology_item.attributes:
                      attr_data = extract_attributes(attribute, object_instance)
                      obj_info["attributes"].append(attr_data)

                      print(f"Attribute name: {attr_data['attribute_name']}")
                      print(f"Attribute hash: {attr_data['attribute_hash']}")
                      print(f"Attribute answer: {attr_data['attribute_answer']}")

                  row_data["objects"].append(obj_info)

      # Process classification annotations
      classification_instances = label_row.get_classification_instances()
      assert classification_instances is not None, f"No classification instances found in label row {label_row.uid}"

      for classification_instance in classification_instances:
          annotations = classification_instance.get_annotations()
          assert annotations, (
              f"No annotations found for classification instance {classification_instance.classification_hash}"
          )

          for annotation in annotations:
              if START_FRAME_NUMBER <= annotation.frame <= END_FRAME_NUMBER:
                  try:
                      answer = classification_instance.get_answer()
                      answer_value = answer.value
                      answer_hash = answer.feature_node_hash
                  except Exception:
                      answer_value = None
                      answer_hash = None

                  classification_info = {
                      "frame": annotation.frame,
                      "classification_hash": classification_instance.classification_hash,
                      "classification_name": classification_instance.classification_name,
                      "feature_hash": classification_instance.feature_hash,
                      "value": answer_value,
                      "answer_hash": answer_hash,
                  }

                  print("Classification hash:", classification_info["classification_hash"])
                  print("Classification name:", classification_info["classification_name"])
                  print("Feature hash:", classification_info["feature_hash"])
                  print("Classification value:", classification_info["value"])
                  print("Classification answer hash:", classification_info["answer_hash"])

                  row_data["classifications"].append(classification_info)

      results.append(row_data)

  # Save to JSON
  assert OUTPUT_FILE_PATH.endswith(".json"), "Output file path must be a JSON file"

  with open(OUTPUT_FILE_PATH, "w") as f:
      json.dump(results, f, indent=4)

  print(f"\nData saved to: {OUTPUT_FILE_PATH}")

  ```

  ```python Frame range for all tasks expandable theme={"dark"}

  # Import dependencies
  import json
  from collections.abc import Iterable

  from encord import EncordUserClient
  from encord.objects import ObjectInstance
  from encord.objects.attributes import Attribute
  from encord.objects.ontology_element import OntologyElement

  # User input
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"
  OUTPUT_FILE_PATH = "/Users/chris-encord/frame_range_output.json"
  START_FRAME_NUMBER = 0
  END_FRAME_NUMBER = 2
  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
  project = user_client.get_project(PROJECT_ID)
  assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"

  # Retrieve all label rows
  label_rows = project.list_label_rows_v2()
  assert label_rows, "No label rows returned from the project"

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)


  # Function to extract attribute info
  def extract_attributes(attribute: Attribute, object_instance: ObjectInstance):
      try:
          answer = object_instance.get_answer(attribute)
      except Exception:
          answer = None
      return {
          "attribute_name": attribute.title,
          "attribute_hash": attribute.feature_node_hash,
          "attribute_answer": str(answer),
      }


  # Store results here
  results = []

  # Iterate over label rows
  for label_row in label_rows:
      row_data = {
          "label_row_hash": label_row.label_hash,
          "data_title": label_row.data_title,
          "objects": [],
          "classifications": [],
      }

      # Process object annotations
      object_instances = label_row.get_object_instances()

      for object_instance in object_instances:
          annotations = object_instance.get_annotations()
          assert annotations, f"No annotations found for object instance {object_instance.object_hash}"

          ontology_item = object_instance.ontology_item
          assert ontology_item and ontology_item.attributes, (
              f"Ontology item or attributes missing for object {object_instance.object_hash}"
          )

          for annotation in annotations:
              if START_FRAME_NUMBER <= annotation.frame <= END_FRAME_NUMBER:
                  obj_info = {
                      "frame": annotation.frame,
                      "object_hash": object_instance.object_hash,
                      "object_name": object_instance.object_name,
                      "feature_hash": object_instance.feature_hash,
                      "uid": str(ontology_item.uid),
                      "color": ontology_item.color,
                      "shape": ontology_item.shape,
                      "label_location": str(annotation.coordinates),
                      "attributes": [],
                  }

                  print("Frame:", annotation.frame)
                  print("objectHash:", object_instance.object_hash)
                  print("Object name:", object_instance.object_name)
                  print("featureHash:", object_instance.feature_hash)
                  print("uid:", obj_info["uid"])
                  print("Object color:", obj_info["color"])
                  print("Ontology shape:", obj_info["shape"])
                  print(f"Label location: {annotation.coordinates}")

                  for attribute in ontology_item.attributes:
                      attr_data = extract_attributes(attribute, object_instance)
                      obj_info["attributes"].append(attr_data)

                      print(f"Attribute name: {attr_data['attribute_name']}")
                      print(f"Attribute hash: {attr_data['attribute_hash']}")
                      print(f"Attribute answer: {attr_data['attribute_answer']}")

                  row_data["objects"].append(obj_info)

      # Process classification annotations
      classification_instances = label_row.get_classification_instances()
      assert classification_instances is not None, f"No classification instances found in label row {label_row.uid}"

      for classification_instance in classification_instances:
          annotations = classification_instance.get_annotations()
          assert annotations, (
              f"No annotations found for classification instance {classification_instance.classification_hash}"
          )

          for annotation in annotations:
              if START_FRAME_NUMBER <= annotation.frame <= END_FRAME_NUMBER:
                  try:
                      answer = classification_instance.get_answer()
                      value = answer.value
                      answer_hash = answer.feature_node_hash
                  except Exception:
                      value = None
                      answer_hash = None

                  classification_info = {
                      "frame": annotation.frame,
                      "classification_hash": classification_instance.classification_hash,
                      "classification_name": classification_instance.classification_name,
                      "feature_hash": classification_instance.feature_hash,
                      "value": value,
                      "answer_hash": answer_hash,
                  }

                  print("Classification hash:", classification_info["classification_hash"])
                  print("Classification name:", classification_info["classification_name"])
                  print("Feature hash:", classification_info["feature_hash"])
                  print("Classification value:", classification_info["value"])
                  print("Classification answer hash:", classification_info["answer_hash"])

                  row_data["classifications"].append(classification_info)

      results.append(row_data)

  # Save everything to JSON
  assert OUTPUT_FILE_PATH.endswith(".json"), "Output file path must end with .json"

  with open(OUTPUT_FILE_PATH, "w") as f:
      json.dump(results, f, indent=4)

  print(f"\nAnnotation data saved to: {OUTPUT_FILE_PATH}")

  ```

  ```Example Output theme={"dark"}
  Frame: 0
  objectHash: U88+HXj4
  Object name: Person
  featureHash: AaaPMAgE
  uid: 1
  Object color: #15d3bc
  Ontology shape: bounding_box
  Label location: BoundingBoxCoordinates(height=0.519561557605036, width=0.15380023056653513, top_left_x=0.43242033102766797, top_left_y=0.0028114478114478862)
  Attribute name: Man or woman
  Attribute hash: X0Xhz9ip
  Attribute answer: NestableOption(feature_node_hash='MN57hMep', uid=[1, 1, 1], label='Man', value='Man', nested_options=[])
  Frame: 44
  objectHash: nZWuD66O
  Object name: Person
  featureHash: AaaPMAgE
  uid: 1
  Object color: #15d3bc
  Ontology shape: bounding_box
  Label location: BoundingBoxCoordinates(height=0.46671424388815697, width=0.1688282279314888, top_left_x=0.37747550230566534, top_left_y=0.07887095593617346)
  Attribute name: Man or woman
  Attribute hash: X0Xhz9ip
  Attribute answer: None
  Classification hash: biZZZov4
  Classification name: Day or Night?
  Feature hash: T+P+wwjw
  Classification value: Day
  Classification answer hash: t+QtqkFp
  ```
</CodeGroup>

### List of non-consecutive frames

The following scripts download and print the labels for specific frames in videos.

Make sure you substitute:

* The \<private\_key\_path> with the full path to your private key.
* The \<project\_hash> with the hash of your Project.
* The \<task\_name> with the name of the file (in Encord) you want to export labels for (if using the task-specific script).
* Replace the numbers in the list `[10, 20, 30, 40]` with the frames you want to export labels for.

<CodeGroup>
  ```python For a specific task theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.objects.ontology_element import OntologyElement
  from encord.objects.attributes import Attribute, Option
  from encord.objects import ObjectInstance
  from collections.abc import Iterable

  # Instantiate Encord client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

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

  # Function to extract and print essential information for all attributes
  def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
      print(f"Attribute name: {attribute.title}")
      print(f"Attribute hash: {attribute.feature_node_hash}")
      print(f"Attribute answer: {object_instance.get_answer(attribute)}")

  # List of specific frames to be exported
  specific_frames = [10, 20, 30, 40]  # Replace with your specific frame numbers

  # Initialize label rows using bundles
  label_rows = project.list_label_rows_v2()
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  for label_row in label_rows:
      # Print essential label information for all objects
      for object_instance in label_row.get_object_instances():
          for annotation in object_instance.get_annotations():
              if annotation.frame in specific_frames:
                  print("Frame: " + str(annotation.frame))
                  print("objectHash: " + object_instance.object_hash)
                  print("Object name: " + object_instance.object_name)
                  print("featureHash: " + object_instance.feature_hash)
                  print("uid: " + str(object_instance.ontology_item.uid))
                  print("Object color: " + object_instance.ontology_item.color)
                  print("Ontology shape: " + object_instance.ontology_item.shape)
                  print(f"Label location: {annotation.coordinates}")

                  # Print all attributes
                  for attribute in object_instance.ontology_item.attributes:
                      print_attributes(attribute, object_instance)

      # Print essential classification information on specified frames
      for classification_instance in label_row.get_classification_instances():
          for annotation in classification_instance.get_annotations():
              if annotation.frame in specific_frames:
                  print("Classification hash: " + classification_instance.classification_hash)
                  print("Classification name: " + classification_instance.classification_name)
                  print("Feature hash: " + classification_instance.feature_hash)
                  print("Classification value: " + classification_instance.get_answer().value)
                  print("Classification answer hash: " + classification_instance.get_answer().feature_node_hash)

  ```

  ```python For all tasks theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.objects.ontology_element import OntologyElement
  from encord.objects.attributes import Attribute, Option
  from encord.objects import ObjectInstance
  from collections.abc import Iterable

  # Instantiate Encord client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

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

  # Function to extract and print essential information for all attributes
  def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
      print(f"Attribute name: {attribute.title}")
      print(f"Attribute hash: {attribute.feature_node_hash}")
      print(f"Attribute answer: {object_instance.get_answer(attribute)}")

  # List of specific frames
  specific_frames = [10, 20, 30, 40]  # Replace with your specific frame numbers

  # Initialize label rows using bundles
  label_rows = project.list_label_rows_v2()
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  for label_row in label_rows:
      # Print essential label information for all objects
      for object_instance in label_row.get_object_instances():
          for annotation in object_instance.get_annotations():
              if annotation.frame in specific_frames:
                  print("Frame: " + str(annotation.frame))
                  print("objectHash: " + object_instance.object_hash)
                  print("Object name: " + object_instance.object_name)
                  print("featureHash: " + object_instance.feature_hash)
                  print("uid: " + str(object_instance.ontology_item.uid))
                  print("Object color: " + object_instance.ontology_item.color)
                  print("Ontology shape: " + object_instance.ontology_item.shape)
                  print(f"Label location: {annotation.coordinates}")

                  # Print all attributes
                  for attribute in object_instance.ontology_item.attributes:
                      print_attributes(attribute, object_instance)

      # Print essential classification information on specified frames
      for classification_instance in label_row.get_classification_instances():
          for annotation in classification_instance.get_annotations():
              if annotation.frame in specific_frames:
                  print("Classification hash: " + classification_instance.classification_hash)
                  print("Classification name: " + classification_instance.classification_name)
                  print("Feature hash: " + classification_instance.feature_hash)
                  print("Classification value: " + classification_instance.get_answer().value)
                  print("Classification answer hash: " + classification_instance.get_answer().feature_node_hash)
  ```

  ```python Example Output theme={"dark"}
  Frame: 10
  objectHash: U88+HXj4
  Object name: Person
  featureHash: AaaPMAgE
  uid: 1
  Object color: #15d3bc
  Ontology shape: bounding_box
  Label location: BoundingBoxCoordinates(height=0.519561557605036, width=0.15380023056653513, top_left_x=0.43242033102766797, top_left_y=0.0028114478114478862)
  Attribute name: Man or woman
  Attribute hash: X0Xhz9ip
  Attribute answer: NestableOption(feature_node_hash='MN57hMep', uid=[1, 1, 1], label='Man', value='Man', nested_options=[])
  Frame: 20
  objectHash: nZWuD66O
  Object name: Person
  featureHash: AaaPMAgE
  uid: 1
  Object color: #15d3bc
  Ontology shape: bounding_box
  Label location: BoundingBoxCoordinates(height=0.46671424388815697, width=0.1688282279314888, top_left_x=0.37747550230566534, top_left_y=0.07887095593617346)
  Attribute name: Man or woman
  Attribute hash: X0Xhz9ip
  Attribute answer: None
  Classification hash: biZZZov4
  Classification name: Day or Night?
  Feature hash: T+P+wwjw
  Classification value: Day
  Classification answer hash: t+QtqkFp
  ```
</CodeGroup>

## Saving Frames with Labels

`ffmpeg` can be used to save all frames with labels as an image, to be used in machine learning applications. The script below shows how this is done when exporting a list of non-consecutive frames from a specific video.

<Note>
  `ffmpeg` must be installed for this script to work.
</Note>

Make sure you substitute:

* The `<output_folder_path>` with the full path to the output folder you want the output image files to be saved.
* The `<private_key_path>` with the full path to your private key.
* The `<project_id>` with the ID of your Project.
* The `<task_name>` with the name of the file in Encord you want to export labels for.
* The `<path_to_your_video_file>` with the full path to the video file you are exporting labels for.
* The `def get_video_path` function to return your actual video path corresponding to the label row.
* Replace the numbers in the list `[10, 20, 30, 40]` with the frames you want to export labels for.

<CodeGroup>
  ```python theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient
  from encord.objects.ontology_element import OntologyElement
  from encord.objects.attributes import Attribute, Option
  from encord.objects import ObjectInstance
  from collections.abc import Iterable
  import subprocess
  import os

  # Specify the output folder path. Replace with your desired folder path
  output_folder = "<output_folder_path>"

  # Create the output folder if it doesn't exist
  if not os.path.exists(output_folder):
      os.makedirs(output_folder)

  def extract_frame_to_image(video_file, frame_number, output_file):
      """
      Uses FFmpeg to extract a specific frame from a video and saves it as an image.
      """
      ffmpeg_command = [
          'ffmpeg', '-i', video_file, '-vf', f'select=eq(n\,{frame_number})',
          '-vframes', '1', output_file
      ]
      subprocess.run(ffmpeg_command, check=True)

  # Instantiate Encord client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

  # Replace with the ID of your Project
  project = user_client.get_project("<project_id>")

  # Function to extract and print essential information for all attributes
  def print_attributes(attribute: Attribute, object_instance: ObjectInstance):
      print(f"Attribute name: {attribute.title}")
      print(f"Attribute hash: {attribute.feature_node_hash}")
      print(f"Attribute answer: {object_instance.get_answer(attribute)}")

  # List of specific frames to be exported. Replace with your specific frame numbers
  specific_frames = [10, 20, 30, 40]

  # Path to the video file you are exporting labels for
  def get_video_path(label_row)
      return "<path_to_your_video_file>"

  # Initialize label rows using bundles
  label_rows = project.list_label_rows_v2()
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  for label_row in label_rows:
      # Print essential label information for all objects
      video_path = get_video_path(label_row)
      for object_instance in label_row.get_object_instances():
          for annotation in object_instance.get_annotations():
              if annotation.frame in specific_frames:
                  print("Frame: " + str(annotation.frame))
                  print("objectHash: " + object_instance.object_hash)
                  print("Object name: " + object_instance.object_name)
                  print("featureHash: " + object_instance.feature_hash)
                  print("uid: " + str(object_instance.ontology_item.uid))
                  print("Object color: " + object_instance.ontology_item.color)
                  print("Ontology shape: " + object_instance.ontology_item.shape)
                  print(f"Label location: {annotation.coordinates}")

                  # Define the output path for the image
                  output_image_path = os.path.join(output_folder, f"frame_{annotation.frame}.png")

                  # Extract and save the specific frame as an image
                  extract_frame_to_image(video_path, annotation.frame, output_image_path)

                  # Print all attributes
                  for attribute in object_instance.ontology_item.attributes:
                      print_attributes(attribute, object_instance)

      # Print essential classification information on specified frames
      for classification_instance in label_row.get_classification_instances():
          for annotation in classification_instance.get_annotations():
              if annotation.frame in specific_frames:
                  print("Classification hash: " + classification_instance.classification_hash)
                  print("Classification name: " + classification_instance.classification_name)
                  print("Feature hash: " + classification_instance.feature_hash)
                  print("Classification value: " + classification_instance.get_answer().value)
                  print("Classification answer hash: " + classification_instance.get_answer().feature_node_hash)
  ```
</CodeGroup>

## Label Editor Coordinates

All label locations are exported as normalized coordinates ranging from 0 to 1. This means that the corners of the frame or image correspond to the coordinates (1,1), (1,0), (0,0), (0,1) regardless of frame dimensions.

To get the pixel values of any normalized coordinates, multiply them by the width or height of the label (given in pixels).

<div>
  <img />
</div>

* "x" and "h" coordinates of a label should be multiplied by the pixel width.
* "y" and "w" coordinates of a label should be multiplied by the pixel height.

## Export Labels from Specific Workflow Stages

<CodeGroup>
  ```python Export from specific stage expandable theme={"dark"}
  from encord import EncordUserClient

  # User input

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the unique Project ID
  WORKFLOW_STAGE = "Annotation" # Replace with the name of the Workflow stage

  # Authentic
  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
  project = user_client.get_project(PROJECT_ID)

  # Fetch label rows in Annotation stage
  label_rows = project.list_label_rows_v2(
      workflow_graph_node_title_eq=WORKFLOW_STAGE
  )

  # Initialise labels
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Export rows
  for label_row in label_rows:
      print(label_row.data_title)
      print(label_row.to_encord_dict())
  ```

  ```python Export from any Review stage expandable theme={"dark"}
  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the unique Project ID
  WORKFLOW_STAGE = "Review%" # Replace with the name of the Workflow stage


  # Authenticate
  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
  project = user_client.get_project(PROJECT_ID)

  # Fetch rows matching Review*
  label_rows = project.list_label_rows_v2(
      workflow_graph_node_title_like=WORKFLOW_STAGE
  )

  # Initialise labels
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Export rows
  for label_row in label_rows:
      stage = label_row.workflow_graph_node.title
      print(f"{label_row.data_title} is in stage: {stage}")
      print(label_row.to_encord_dict())
  ```

  ```python Export all labels expandable theme={"dark"}

  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the unique Project ID
  WORKFLOW_STAGE = "Review%" # Replace with the name of the Workflow stage


  # Authenticate
  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
  project = user_client.get_project(PROJECT_ID)

  # Fetch all label rows
  label_rows = project.list_label_rows_v2()

  # Initialise labels
  with project.create_bundle() as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Process depending on stage
  for label_row in label_rows:
      stage = label_row.workflow_graph_node.title if label_row.workflow_graph_node else None

      print(f"{label_row.data_title} is in stage: {stage}")

      if stage == "Annotation":
          print("Processing annotation row")
          print(label_row.to_encord_dict())

      elif stage == "Review":
          print("Processing review row")
          print(label_row.to_encord_dict())

  ```
</CodeGroup>

## Export all Consensus labels

[Consensus Projects](/platform-documentation/Annotate/annotate-projects/annotate-workflows-consensus) introduce the concept of BRANCHES within the task workflow. A Consensus annotation task consists of a MAIN branch and one sub-branch for each Annotator. Each time an annotator saves or submits a task, the annotator creates their own branch on a task. The MAIN branch remains empty of labels until a reviewer specifies that a task is in consensus. When consensus is reached, the labels that are the best representative set move to the MAIN branch. To export all labels (labels generated for every branch on every data unit) from your Consensus Project, use `include_all_branches=True`.

Make sure you:

* Substitute the `<private_key_path>` with the full path to your private key.
* Substitute the `<project_id>` with the ID of your Project.
* If you only want to export the MAIN branch, remove `include_all_label_branches=True`.

<Note>
  - Adding `include_all_label_branches=True` to `list_label_rows_v2()` includes all labels from all branches in Consensus Projects.
</Note>

<Warning>
  **Deprecated (SDK v0.1.195):** For Data Groups, passing `include_children=True` to `list_label_rows_v2()` to fetch child labels is deprecated. Work on the Data Group **parent** instead and access each child through its Label Space with [`LabelRowV2.get_spaces()`](/sdk-documentation/sdk-labels/sdk-data-group-labels#get-label-spaces).
</Warning>

<CodeGroup>
  ```python All labels all branches expandable theme={"dark"}

  import json

  from encord import EncordUserClient

  # User input
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "00000000-0000-0000-0000-000000000000"
  OUTPUT_FILE_PATH = "/Users/chris-encord/frame_range_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",
  )

  # Specify Project. Replace <project_id> with the ID of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Downloads a local copy of all the labels
  # Without the include_all_label_branches flag only the MAIN branch labels export.
  # Data Group child labels are returned on the parent row, so include_children is
  # not needed (it is deprecated since SDK v0.1.195).
  label_rows = project.list_label_rows_v2(include_all_label_branches=True)

  output_data = []  # This will hold the output data to be saved as JSON

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Collecting data for JSON output
  for label_row in label_rows:
      label_row_data = {
          "title": label_row.data_title,
          "branch": label_row.branch_name,
          "objects": [],
          "classifications": [],
      }

      # Collect object instances
      for object_instance in label_row.get_object_instances():
          object_data = {
              "object_hash": object_instance.object_hash,
              "object_name": object_instance.object_name,
              "feature_hash": object_instance.feature_hash,
              "ontology_item": {
                  "uid": object_instance.ontology_item.uid,
                  "color": object_instance.ontology_item.color,
                  "shape": object_instance.ontology_item.shape,
                  "attributes": [
                      {"name": attribute.name, "value": attribute.value}
                      for attribute in object_instance.ontology_item.attributes
                  ],
              },
              "annotations": [
                  {"frame": annotation.frame, "coordinates": annotation.coordinates}
                  for annotation in object_instance.get_annotations()
              ],
          }
          label_row_data["objects"].append(object_data)

      # Collect classification instances
      for classification_instance in label_row.get_classification_instances():
          classification_data = {
              "classification_hash": classification_instance.classification_hash,
              "classification_name": classification_instance.classification_name,
              "feature_hash": classification_instance.feature_hash,
              "classification_answer": {
                  "value": classification_instance.get_answer().value,
                  "hash": classification_instance.get_answer().feature_node_hash,
              },
              "annotations": [{"frame": annotation.frame} for annotation in classification_instance.get_annotations()],
          }
          label_row_data["classifications"].append(classification_data)

      # Add label row data to the output list
      output_data.append(label_row_data)

  # Saving to JSON file
  output_file_path = OUTPUT_FILE_PATH  # Replace with the desired file path
  with open(output_file_path, "w") as json_file:
      json.dump(output_data, json_file, indent=4)

  print(f"Output saved to {output_file_path}")

  ```
</CodeGroup>

***

## Export all Data Group labels

For Data Groups, all child labels are exported through the Data Group **parent**. Call `list_label_rows_v2()` (without `include_children`) and export the parent rows — each child's labels are included in the parent's exported dictionary. The first example below is the recommended approach; the second is retained for reference only.

<Note>
  * Adding `include_all_label_branches=True` to `list_label_rows_v2()` includes all labels from all branches in Consensus Projects.
</Note>

<Warning>
  **Deprecated (SDK v0.1.195):** For Data Groups, passing `include_children=True` to `list_label_rows_v2()` to fetch child labels is deprecated. Work on the Data Group **parent** instead and access each child through its Label Space with [`LabelRowV2.get_spaces()`](/sdk-documentation/sdk-labels/sdk-data-group-labels#get-label-spaces).
</Warning>

<CodeGroup>
  ```python Export labels to JSON expandable theme={"dark"}

  # Import dependencies
  import json
  import os

  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with Project unique ID
  BUNDLE_SIZE = 100  # Customize as needed
  OUTPUT_JSON = "/Users/chris-encord/export-label-rows.json" # Replace with file path to save JSON output file

  # 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",
  )

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

  # Get label rows for your Project
  label_rows = project.list_label_rows_v2()
  assert label_rows, f"No label rows found in project {PROJECT_ID}"

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Collect all label row data
  all_label_rows = [label_row.to_encord_dict() for label_row in label_rows]
  assert all_label_rows, "No label row data collected for export"

  # Save the collected label rows data to a JSON file
  output_file = OUTPUT_JSON
  assert output_file.endswith(".json"), "Output file must be a .json file"

  with open(output_file, "w") as file:
      json.dump(all_label_rows, file, indent=4)

  print(f"Label rows have been saved to {output_file}.")
  ```

  ```python DEPRECATED: Export labels to JSON expandable theme={"dark"}

  # Import dependencies
  import json
  import os

  from encord import EncordUserClient

  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
  PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with Project unique ID
  BUNDLE_SIZE = 100  # Customize as needed
  OUTPUT_JSON = "/Users/chris-encord/export-label-rows.json" # Replace with file path to save JSON output file

  # 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",
  )

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

  # Get label rows for your Project
  # DEPRECATED (SDK v0.1.195): include_children=True is deprecated. Prefer the
  # parent-based export (list_label_rows_v2() without include_children), which
  # returns each Data Group child's labels on the parent row.
  label_rows = project.list_label_rows_v2(include_children=True)
  assert label_rows, f"No label rows found in project {PROJECT_ID}"

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Collect all label row data
  all_label_rows = [label_row.to_encord_dict() for label_row in label_rows]
  assert all_label_rows, "No label row data collected for export"

  # Save the collected label rows data to a JSON file
  output_file = OUTPUT_JSON
  assert output_file.endswith(".json"), "Output file must be a .json file"

  with open(output_file, "w") as file:
      json.dump(all_label_rows, file, indent=4)

  print(f"Label rows have been saved to {output_file}.")

  ```
</CodeGroup>

***

## Export Bitmasks

The following code example illustrates how to download / export and save Bitmask labels:

```python theme={"dark"}
import cv2
import numpy as np
from encord import EncordUserClient

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Specify a project using project hash
project = user_client.get_project("<project_hash>")

# Obtain labels for the media of interest
label_row = project.list_label_rows_v2()[0]
label_row.initialise_labels()

# Find annotation
# In this example, it is just a first object on a first frame
object_with_bitmask_annotation = label_row.get_frame_views()[
    0
].get_object_instances()[0]

# Get a bitmask annotation
# In this example, it is a first annotation on the object
bitmask_annotation = object_with_bitmask_annotation.get_annotations()[0]

# Convert bitmask to a numpy array
# Obtained array is a binary mask, so to work with it as an image,
# it is necessary to convert it to a different datatype and scale
bitmask = bitmask_annotation.coordinates.to_numpy_array().astype(np.uint8)

bitmask[bitmask == 1] = 255

# And now we can save the mask as a grayscale image
cv2.imwrite("./mask_as_an_image.png", bitmask)
```

## Decode Bitmask Labels

Bitmask labels exported from Encord as JSON or COCO are encoded as an `rleString`. This `rleString` can be converted to an image or a binary array.

<Info>
  Use the [COCO API](https://github.com/cocodataset/cocoapi) to decode Bitmasks when using the COCO export format.
</Info>

<AccordionGroup>
  <Accordion title="Create Bitmask Image">
    <CodeGroup>
      ```python JSON Format theme={"dark"}
      # Import dependencies
      import json
      from pathlib import Path
      import numpy as np
      from encord.objects.coordinates import BitmaskCoordinates
      from PIL import Image

      # Read the JSON file.
      # Replace labels.json with the path to the JSON file containing your Bitmask
      labels = json.loads(Path("labels.json").read_text())
      output_folder = Path("output")
      output_folder.mkdir(parents=True, exist_ok=True)

      # Finds the rleString and saves it to a .png image
      found_any = False
      for label_row in labels:
          for du in label_row["data_units"].values():
              slice_nums = list(du["labels"].keys())
              for slice_num in slice_nums:
                  for obj in du["labels"][slice_num]["objects"]:
                      bmc = BitmaskCoordinates.from_dict(obj)
                      nparr = np.array(bmc)
                      img = Image.fromarray(nparr)
                      # img.show()
                      # Replace example.png with the name of the output file
                      img.save(output_folder / f"mask_{int(slice_num):05d}_{obj['objectHash']}.png")
      print("Decoding complete.")
      ```

      ```python COCO Format theme={"dark"}
      from pycocotools.coco import COCO
      import numpy as np
      from pycocotools import mask as maskUtils
      from PIL import Image
      import json


      # Read the COCO file. Replace 'labels.json' with the path to your COCO format annotations file
      coco_annotations_path = 'labels.json'
      coco = COCO(coco_annotations_path)

      # Get all annotation IDs (you might want to filter or select specific ones)
      annIds = coco.getAnnIds()
      anns = coco.loadAnns(annIds)

      # Decode each rleString and save as a .png image
      for i, ann in enumerate(anns):
          if 'segmentation' in ann and isinstance(ann['segmentation'], dict):

              rle = ann['segmentation']
              
              mask = maskUtils.decode(rle)

              img = Image.fromarray(mask * 255).convert('L')  # Convert to grayscale

      # Replace example.png with the name of the output file
              img.save("example.png")

      print("Decoding complete.")
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Create Binary Array">
    The `rleString`can be converted into an array of 1's and 0's using the script below.

    ```python theme={"dark"}
    from encord.objects.coordinates import BitmaskCoordinates

    # Create a numpy array
    np_mask = BitmaskCoordinates.from_dict(obj).to_numpy_array() 
    print(np_mask.astype(int))

    ```
  </Accordion>
</AccordionGroup>

***

## Bulk Export Labels

Use the [bundle](/sdk-documentation/sdk-references/http.bundle#bundle) function to significantly improve export performance.

<Info>
  We strongly recommend NOT bundling more than 1000 operations at once, because
  bundling more than 1000 operations can reduce performance instead of improving
  performance.
</Info>

<Warning>
  In the following code, ensure you replace:

  * `<private_key_path>` with the full path to your private key.
  * `<project-id>` with the ID of the Project you want to export labels for.
  * `#Perform label row operation before in this loop` with the label row operations you want to perform.
  * Optionally, change the value of `BUNDLE_SIZE` to suit your needs. We strongly recommend NOT bundling more than 1000 operations at once, because bundling more than 1000 operations can reduce performance instead of improving performance.
</Warning>

<CodeGroup>
  ```python theme={"dark"}

  # Import dependencies
  from pathlib import Path

  from encord import EncordUserClient, Project
  from encord.objects import (
      Object,
      ObjectInstance,
      OntologyStructure,
  )
  from encord.objects.coordinates import BoundingBoxCoordinates

  SSH_PATH = "<private-key-path>"
  PROJECT_ID = "<project-id>"

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

  # Gets Project to export labels
  project: Project = user_client.get_project(PROJECT_ID)

  label_rows = project.list_label_rows_v2()
  BUNDLE_SIZE = 100

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  for label_row in label_rows:

      # Write any label row operation here. For example import, or export label rows.


  # Saving changes to label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.save(bundle=bundle)

  ```
</CodeGroup>

### Export Classifications Only

When you only need the classification answers for a Project, `get_label_classifications()` provides a fast bulk path that fetches classification answers directly, without initializing each full label row. Object annotations, frames, and coordinates are not returned.

<Info>
  This script DOES NOT use the [bundle](/sdk-documentation/sdk-references/http.bundle#bundle-objects) function shown above. Requests are batched server-side using the `batch_size` argument (max `1000` labels per request), so the batching benefit is already built into the method.
</Info>

The following script fetches classification answers for every label row in a Project and saves them to a JSON file.

```python Export classifications (bulk) to JSON expandable theme={"dark"}

# Import dependencies
import json

from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with Project unique ID
BRANCH_NAME = "main"  # Replace with the label branch to read from
BATCH_SIZE = 500  # Number of labels per server request (max 1000). Customize as needed
OUTPUT_JSON = "/Users/chris-encord/export-classifications.json" # Replace with file path to save JSON output file

# 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",
)

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

# Get label rows for your Project
label_rows = project.list_label_rows_v2()
assert label_rows, f"No label rows found in project {PROJECT_ID}"

# Collect the label row UUIDs (label_hash) to fetch classifications for
label_uuids = [row.label_hash for row in label_rows if row.label_hash is not None]
assert label_uuids, f"No created label rows found in project {PROJECT_ID}"

# Fast bulk fetch of classification answers only.
# Requests are batched automatically, so no bundle is required here.
all_classifications = [
    entry.to_dict()
    for entry in project.get_label_classifications(
        label_uuids,
        branch_name=BRANCH_NAME,
        batch_size=BATCH_SIZE,
    )
]
assert all_classifications, "No classification data collected for export"

# Save the collected classifications to a JSON file
output_file = OUTPUT_JSON
assert output_file.endswith(".json"), "Output file must be a .json file"

with open(output_file, "w") as file:
    json.dump(all_classifications, file, indent=4)

print(f"Classifications for {len(all_classifications)} label rows have been saved to {output_file}.")

```

## COCO Format Export

Use the following script to bulk export labels in the COCO format.

Ensure that you replace:

* `<private-key-path>` with the full path to your private key for authentication.
* `<project-id>` with the ID of the Project for which you want to export labels.

```python COCO Export theme={"dark"}
from encord import EncordUserClient
import json


SSH_PATH = "/Users/chris-encord/ssh-private-key.txt" # Replace with the access key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the unique ID for the Project

# 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",
)

project = user_client.get_project(PROJECT_ID)
coco_labels = project.export_coco_labels()

# Save the coco_labels dictionary to a .json file
with open("coco_labels.json", "w") as json_file:
    json.dump(coco_labels, json_file)

```


# COCO Labels/Annotations
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-coco-labels



Encord's SDK supports importing labels/annotations for your data in the COCO format.

You can also import your [COCO labels/annotations as predictions on your Active Projects](/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud).

<Note>This guide assumes your files were already [imported into Encord](/sdk-documentation/getting-started-sdk/sdk-register-data-aws) and a [Project containing the data has been created](/sdk-documentation/getting-started-sdk/sdk-get-started-ontology).</Note>

1. Save `import.py`, replacing the following variables:
   * `<private_key_path>` with the full path to your private key.
   * `<project_id>` with the unique ID of the Project containing the data units you want to import labels for.
   * `COCOimportfile.json` with the full path of the COCO file containing the labels you want to import.

<Info>The COCO file MUST include the `info` field. If it is missing, add it as: `"info": {},`.</Info>

2. If necessary, modify the matching logic that maps COCO image IDs to Encord frame indices. This is particularly important in cases where filenames in the COCO file do not directly match those in the Encord Project or when multiple files have the same name.

The following `import.py` script is configured to import labels into single images with unique names and assumes that the category names in the COCO file match the names of your Ontology objects.

In practice, you must implement your own matching logic. An example where filenames in the COCO file do not directly match those in the Encord Project is provided below.

<CodeGroup>
  ```python import.py theme={"dark"}
  import json
  from pathlib import Path
  from encord.utilities.coco.datastructure import FrameIndex
  from encord import EncordUserClient
  from encord.exceptions import OntologyError

  # Replace with the path to your SSH private key
  keyfile = "<private_key_path>"

  # Authenticate with Encord using your SSH private key
  user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path=keyfile)

  # Replace with your Project ID
  project = user_client.get_project("<project_id>")

  # Load the COCO annotations JSON file
  # Replace 'COCOimportfile.json' with the full path to your COCO file
  coco_file = Path('COCOimportfile.json')
  labels_dict = json.loads(coco_file.read_text())

  # Build a mapping from COCO category IDs to the feature hashes in your Encord Ontology. 
  category_id_to_feature_hash = {}
  ont_struct = project.ontology_structure
  for coco_category in labels_dict['categories']:
      try:
          ont_obj = ont_struct.get_child_by_title(coco_category['name'])
          category_id_to_feature_hash[coco_category['id']] = ont_obj.feature_node_hash
      except OntologyError:
          print(f'Could not match {coco_category["name"]} in the Ontology. Import will crash if these are present.')

  # Build a mapping from COCO image IDs to Encord frame indices
  # This is only applicable for images, image groups, image sequences, and DICOM series
  image_id_to_frame_index = {}
  data_title_to_label_row = {lr.data_title: lr for lr in project.list_label_rows_v2()}
  for img in labels_dict['images']:
      if "video_title" in img.keys():
          lr = data_title_to_label_row[img["video_title"]]
          frame_num = int(img["file_name"].split('/')[-1].split(".")[0])
      else:
          lr = data_title_to_label_row[img['image_title']]
          frame_num = 0

      # Creates a mapping between the COCO image IDs and the corresponding frame indices in Encord
      # In this example, the target frame is 0 because the files in the sample project are single images
      image_id_to_frame_index[img['id']] = FrameIndex(lr.data_hash, frame=frame_num)

  # Import the COCO labels into Encord
  project.import_coco_labels(
      labels_dict,
      category_id_to_feature_hash,
      image_id_to_frame_index
  )
  ```

  ```json COCO example Bounding Box theme={"dark"}
  {
    "info": {},
    "images": [
      {
        "id": 1,
        "file_name": "cutekitty.jpg",
        "height": 480,
        "width": 640
      },
      {
        "id": 2,
        "file_name": "cutepuppy.jpg",
        "height": 480,
        "width": 640
      }
    ],
    "annotations": [
      {
        "id": 1,
        "image_id": 1,
        "category_id": 1,
        "bbox": [246, 251, 153, 159],
        "area": 1234.56,
        "iscrowd": false
      },
      {
        "id": 2,
        "image_id": 2,
        "category_id": 2,
        "bbox": [220, 236, 76, 64],
        "area": 5678.90,
        "iscrowd": true
      }
    ],
    "categories": [
      {
        "id": 1,
        "name": "Cat",
        "supercategory": "bounding_box"
      },
      {
        "id": 2,
        "name": "Dog",
        "supercategory": "bounding_box"
      }
    ]
  }
  ```

  ```json COCO example Polygon theme={"dark"}
  {
    "info": {},
    "images": [
      {
        "id": 1,
        "file_name": "cutekitty.jpg",
        "height": 480,
        "width": 640
      },
      {
        "id": 2,
        "file_name": "cutepuppy.jpg",
        "height": 480,
        "width": 640
      }
    ],
    "annotations": [
      {
        "id": 1,
        "image_id": 1,
        "category_id": 1,
        "segmentation": [508, 559, 512, 555, 517, 554, 520, 548, 527, 542, 531, 540, 538, 540, 553, 562],
        "area": 1234.56,
        "iscrowd": false
      },
      {
        "id": 2,
        "image_id": 2,
        "category_id": 2,
        "segmentation": [508, 559, 512, 555, 517, 554, 520, 548, 527, 542, 531, 540, 538, 540, 553, 562],
        "area": 5678.90,
        "iscrowd": true
      }
    ],
    "categories": [
      {
        "id": 1,
        "name": "Cat",
        "supercategory": "polygon"
      },
      {
        "id": 2,
        "name": "Dog",
        "supercategory": "polygon"
      }
    ]
  }
  ```

  ```python Filename mismatch theme={"dark"}
  data_title_to_label_row = {lr.data_title: lr for lr in project.list_label_rows_v2()}
  for img in labels_dict['images']:
      fname = img['file_name']
      stem = fname.split('/')[0]  # Adjust based on your filename structure
      assert stem in data_title_to_label_row, f'Problem matching {stem}'
      lr = data_title_to_label_row[stem]
      image_id_to_frame_index[img['id']] = FrameIndex(lr.data_hash, frame=0)
  ```
</CodeGroup>


# Images & Videos
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual



Once you have imported your [local data](/sdk-documentation/index-sdk/sdk-upload-data#upload-local-data-to-an-existing-folder) or [cloud data](/sdk-documentation/getting-started-sdk/sdk-register-data-aws) into Encord, you can import your labels/annotations for the data.

<Info>You MUST call the [initialise\_labels](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects#initialise-labels) function (once per data unit) before you can import your labels/annotations.</Info>

The process to import labels into Encord consists of the following:

1. Import the dependencies.
2. Authenticate your Encord client.
3. Specify the Annotate Project with the data you want to label.
4. Specify the label row you want to import your label to. This specifies the data unit (image, image group, image sequence, video, or DICOM series) you want to add your labels to.
5. Use the [initialise\_labels](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects#initialise-labels) function ONCE to prepare the row for your labels.
6. Apply your labels to the label row.
7. Save the label row.

<Note>One label row is equivalent to one data unit. You only need to use the [initialise\_labels](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects#initialise-labels) function and save the label row ONCE per data unit, regardless of how many labels are added to the data unit. However, any future changes to a data unit need to be initialized and saved.</Note>

## Object Labels

<AccordionGroup>
  <Accordion title="Bounding Box">
    **Basic**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling

    **Advanced**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling
    * Radio button options
    * Checklist options
    * Text input
    * Number input

    **Bounding Box Ontology**

    ![Bounding Box Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/labels-bounding-box-cherries.png)

    <CodeGroup>
      ```python Bounding Boxes Images/Videos - Basic expandable theme={"dark"}

      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BoundingBoxCoordinates

      # 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 Project ID
      BUNDLE_SIZE = 10

      # Data unit titles in your Project.
      IMAGE_TITLE = "cherries-001.jpg"
      IMG_GROUP_TITLE = "cherries-ig"
      IMG_SEQUENCE_TITLE = "cherries-is"
      VIDEO_TITLE = "cherries-vid-001.mp4"

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Find bounding box object "Cherries" in the ontology.
      ontology_structure = project.ontology_structure
      box_ontology_object: Object = ontology_structure.get_child_by_title(title="Cherries", type_=Object)
      assert box_ontology_object is not None, "Bounding box object 'Cherries' not found in ontology."

      # Initialise label rows
      label_rows = {}
      all_titles = [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in all_titles:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Coordinates for the bounding box
      box = BoundingBoxCoordinates(height=0.35, width=0.35, top_left_x=0.1, top_left_y=0.1)

      # Create instances and attach to frames
      label_rows_to_save = []

      # 1. One image > annotate frame 0
      image_lr = label_rows.get(IMAGE_TITLE)
      if image_lr is not None:
          inst: ObjectInstance = box_ontology_object.create_instance()
          inst.set_for_frames(coordinates=box, frames=0)
          image_lr.add_object_instance(inst)
          label_rows_to_save.append(image_lr)

      # 2. One image group > annotate frame 0
      img_group_lr = label_rows.get(IMG_GROUP_TITLE)
      if img_group_lr is not None:
          inst: ObjectInstance = box_ontology_object.create_instance()
          inst.set_for_frames(coordinates=box, frames=0)
          img_group_lr.add_object_instance(inst)
          label_rows_to_save.append(img_group_lr)

      # 3. One image sequence > annotate frame 0
      img_sequence_lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if img_sequence_lr is not None:
          inst: ObjectInstance = box_ontology_object.create_instance()
          inst.set_for_frames(coordinates=box, frames=0)
          img_sequence_lr.add_object_instance(inst)
          label_rows_to_save.append(img_sequence_lr)

      # 4. One video > reuse SAME instance across 3 consecutive frames (frames 100, 101, 102)
      video_lr = label_rows.get(VIDEO_TITLE)
      if video_lr is not None:
          inst: ObjectInstance = box_ontology_object.create_instance()
          consecutive_frames = [100, 101, 102]
          for f in consecutive_frames:
              inst.set_for_frames(coordinates=box, frames=f)
          video_lr.add_object_instance(inst)
          label_rows_to_save.append(video_lr)

      # Save the label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in label_rows_to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: created one bounding box on image, image group, image sequence, and 3 video frames.")
      ```

      ```python Bounding Boxes Images/Videos - Advanced expandable theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient, Project
      from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
      from encord.objects.attributes import NumericAttribute
      from encord.objects.coordinates import BoundingBoxCoordinates

      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)

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

      # Find a bounding box annotation object in the project ontology
      box_ontology_object: Object = ontology_structure.get_child_by_title(title="Cherries", type_=Object)
      assert box_ontology_object is not None, "Bounding box object 'Cherries' not found in ontology."

      # Find radio attribute in the ontology
      cherry_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert cherry_type_radio_attribute is not None, "Radio attribute 'Type?' not found in ontology."

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

      # Create options for the radio buttons
      bing_option = cherry_type_radio_attribute.get_child_by_title(type_=Option, title="Bing")
      king_option = cherry_type_radio_attribute.get_child_by_title(type_=Option, title="King")
      rainier_option = cherry_type_radio_attribute.get_child_by_title(type_=Option, title="Rainier")
      other_cherry_option = cherry_type_radio_attribute.get_child_by_title(type_=Option, title="Other cherry type")

      assert all([bing_option, king_option, rainier_option, other_cherry_option]), (
          "One or more cherry type options are missing."
      )

      # Bing Qualities
      bing_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Bing Qualities?")
      assert bing_checklist_attribute is not None, "Checklist attribute 'Bing Qualities?' not found."

      bing_plump_option = bing_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      bing_juicy_option = bing_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      bing_large_option = bing_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert all([bing_plump_option, bing_juicy_option, bing_large_option]), "One or more Bing quality options are missing."

      # King Qualities
      king_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="King Qualities?")
      assert king_checklist_attribute is not None, "Checklist attribute 'King Qualities?' not found."

      king_plump_option = king_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      king_juicy_option = king_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      king_large_option = king_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert all([king_plump_option, king_juicy_option, king_large_option]), "One or more King quality options are missing."

      # Rainier Qualities
      rainier_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Rainier Qualities?"
      )
      assert rainier_checklist_attribute is not None, "Checklist attribute 'Rainier Qualities?' not found."

      rainier_plump_option = rainier_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      rainier_juicy_option = rainier_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      rainier_large_option = rainier_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert all([rainier_plump_option, rainier_juicy_option, rainier_large_option]), (
          "One or more Rainier quality options are missing."
      )

      # Other Cherry Types
      other_cherry_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify cherry type"
      )
      assert other_cherry_option_text_attribute is not None, "Text attribute 'Specify cherry type' not found in ontology."

      # Dictionary of labels per data unit and per frame with cherry type specified, including quality options
      video_frame_labels = {
          "cherries-001.jpg": {
              0: {
                  "label_ref": "cherry_001",
                  "coordinates": BoundingBoxCoordinates(height=0.4, width=0.4, top_left_x=0.0, top_left_y=0.0),
                  "cherry_type": "Bing",
                  "bing_quality_options": "Plump, Juicy",
                  "cherry_quality": 4
              }
          },
          "cherries-010.jpg": {
              0: [
                  {
                      "label_ref": "cherry_002",
                      "coordinates": BoundingBoxCoordinates(height=0.4, width=0.4, top_left_x=0.0, top_left_y=0.0),
                      "cherry_type": "King",
                      "king_quality_options": "Plump, Juicy, Large",
                      "cherry_quality": 9
                  },
                  {
                      "label_ref": "cherry_003",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.1, top_left_x=0.5, top_left_y=0.0),
                      "cherry_type": "Rainier",
                      "rainier_quality_options": "Plump",
                      "cherry_quality": 5
                  },
                  {
                      "label_ref": "cherry_004",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.1, top_left_x=0.7, top_left_y=0.0),
                      "cherry_type": "Other cherry type",
                      "Specify cherry type": "Morello",
                      "cherry_quality": 3
                  },
              ],
          },
          "cherries-ig": {
              0: {
                  "label_ref": "cherry_005",
                  "coordinates": BoundingBoxCoordinates(height=0.4, width=0.4, top_left_x=0.0, top_left_y=0.0),
                  "cherry_type": "Bing",
                  "bing_quality_options": "Plump, Juicy",
                  "cherry_quality": 7
              },
              2: [
                  {
                      "label_ref": "cherry_006",
                      "coordinates": BoundingBoxCoordinates(height=0.1, width=0.2, top_left_x=0.5, top_left_y=0.0),
                      "cherry_type": "King",
                      "king_quality_options": "Large",
                      "cherry_quality": 6
                  },
                  {
                      "label_ref": "cherry_007",
                      "coordinates": BoundingBoxCoordinates(height=0.1, width=0.2, top_left_x=0.0, top_left_y=0.5),
                      "cherry_type": "Rainier",
                      "rainier_quality_options": "Plump",
                      "cherry_quality": 6
                  },
                  {
                      "label_ref": "cherry_008",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.1, top_left_x=0.8, top_left_y=0.0),
                      "cherry_type": "Other cherry type",
                      "Specify cherry type": "Queen Anne",
                      "cherry_quality": 3
                  },
              ],
          },
          "cherries-is": {
              0: {
                  "label_ref": "cherry_009",
                  "coordinates": BoundingBoxCoordinates(height=0.4, width=0.4, top_left_x=0.0, top_left_y=0.0),
                  "cherry_type": "Bing",
                  "bing_quality_options": "Plump",
                  "cherry_quality": 4
              },
              3: [
                  {
                      "label_ref": "cherry_010",
                      "coordinates": BoundingBoxCoordinates(height=0.4, width=0.4, top_left_x=0.5, top_left_y=0.0),
                      "cherry_type": "King",
                      "king_quality_options": "Plump, Juicy, Large",
                      "cherry_quality": 8
                  },
                  {
                      "label_ref": "cherry_011",
                      "coordinates": BoundingBoxCoordinates(height=0.3, width=0.3, top_left_x=0.0, top_left_y=0.5),
                      "cherry_type": "Rainier",
                      "rainier_quality_options": "Plump",
                  },
                  {
                      "label_ref": "cherry_012",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.1, top_left_x=0.9, top_left_y=0.0),
                      "cherry_type": "Other cherry type",
                      "Specify cherry type": "Lambert",
                      "cherry_quality": 4
                  },
              ],
          },
          "cherries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "cherry_013",
                      "coordinates": BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.0, top_left_y=0.0),
                      "cherry_type": "Rainier",
                      "rainier_quality_options": "Plump",
                       "cherry_quality": 5
                  },
                  {
                      "label_ref": "cherry_014",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.2, top_left_x=0.6, top_left_y=0.0),
                      "cherry_type": "Bing",
                      "bing_quality_options": "Plump, Juicy, Large",
                      "cherry_quality": 9
                  },
                  {
                      "label_ref": "cherry_015",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.1, top_left_x=0.8, top_left_y=0.6),
                      "cherry_type": "Other cherry type",
                      "Specify cherry type": "Sweetheart",
                      "cherry_quality": 7
                  },
              ],
              104: [
                  {
                      "label_ref": "cherry_016",
                      "coordinates": BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.0, top_left_y=0.0),
                      "cherry_type": "Rainier",
                      "rainier_quality_options": "Plump",
                      "cherry_quality": 7
                  },
                  {
                      "label_ref": "cherry_014",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.2, top_left_x=0.6, top_left_y=0.0),
                      "cherry_type": "Bing",
                      "bing_quality_options": "Plump, Juicy, Large",
                      "cherry_quality": 9
                  },
                  {
                      "label_ref": "cherry_017",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.1, top_left_x=0.8, top_left_y=0.6),
                      "cherry_type": "Other cherry type",
                      "Specify cherry type": "Sweetheart",
                      "cherry_quality": 2
                  },
              ],
              105: [
                  {
                      "label_ref": "cherry_016",
                      "coordinates": BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.0, top_left_y=0.0),
                      "cherry_type": "Rainier",
                      "rainier_quality_options": "Plump",
                       "cherry_quality": 7
                  },
                  {
                      "label_ref": "cherry_014",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.2, top_left_x=0.6, top_left_y=0.0),
                      "cherry_type": "Bing",
                      "bing_quality_options": "Plump, Juicy, Large",
                      "cherry_quality": 9
                  },
                  {
                      "label_ref": "cherry_017",
                      "coordinates": BoundingBoxCoordinates(height=0.2, width=0.1, top_left_x=0.8, top_left_y=0.6),
                      "cherry_type": "Other cherry type",
                      "Specify cherry type": "Sweetheart",
                      "cherry_quality": 3
                  },
              ],
          },
      }

      # Cache initialized label rows
      label_row_map = {}

      # Step 1: Initialize all label rows using a bundle
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for data_unit in video_frame_labels.keys():
              label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
              assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"

              if not label_rows:
                  print(f"Skipping: No label row found for {data_unit}")
                  continue

              label_row = label_rows[0]
              label_row.initialise_labels(bundle=bundle)
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              label_row_map[data_unit] = label_row  # Cache initialized label row for later use

      # Step 2: Process all frames/annotations and prepare label rows to save
      label_rows_to_save = []

      for data_unit, frame_coordinates in video_frame_labels.items():
          label_row = label_row_map.get(data_unit)
          if not label_row:
              print(f"Skipping: No initialized label row found for {data_unit}")
              continue

          object_instances_by_label_ref = {}

          # Loop through the frames for the current data unit
          for frame_number, items in frame_coordinates.items():
              assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"
              if not isinstance(items, list):
                  items = [items]

              for item in items:
                  label_ref = item["label_ref"]
                  coord = item["coordinates"]
                  cherry_type = item["cherry_type"]
                  cherry_quality = item["cherry_quality"]

                  assert cherry_type in {
                      "Bing",
                      "King",
                      "Rainier",
                      "Other cherry type",
                  }, f"Unexpected cherry type '{cherry_type}' in data unit '{data_unit}'"

                  # Check if label_ref already exists for reusability
                  if label_ref not in object_instances_by_label_ref:
                      box_object_instance: ObjectInstance = box_ontology_object.create_instance()
                      assert box_object_instance is not None, "Failed to create ObjectInstance"

                      object_instances_by_label_ref[label_ref] = box_object_instance
                      checklist_attribute = None

                      # Set cherry quality attribute 
                      box_object_instance.set_answer(attribute=cherry_quality_number_attribute, answer=cherry_quality)

                      # Set cherry type attribute
                      if cherry_type == "Bing":
                          assert bing_option is not None, "Missing 'bing_option'"
                          box_object_instance.set_answer(attribute=cherry_type_radio_attribute, answer=bing_option)
                          checklist_attribute = bing_checklist_attribute
                      elif cherry_type == "King":
                          assert king_option is not None, "Missing 'king_option'"
                          box_object_instance.set_answer(attribute=cherry_type_radio_attribute, answer=king_option)
                          checklist_attribute = king_checklist_attribute
                      elif cherry_type == "Rainier":
                          assert rainier_option is not None, "Missing 'rainier_option'"
                          box_object_instance.set_answer(attribute=cherry_type_radio_attribute, answer=rainier_option)
                          checklist_attribute = rainier_checklist_attribute
                      elif cherry_type == "Other cherry type":
                          assert other_cherry_option is not None, "Missing 'other_cherry_option'"
                          box_object_instance.set_answer(attribute=cherry_type_radio_attribute, answer=other_cherry_option)
                          text_answer = item.get("Specify cherry type", "")
                          assert isinstance(text_answer, str), "'Specify cherry type' must be a string"
                          box_object_instance.set_answer(attribute=other_cherry_option_text_attribute, answer=text_answer)

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

                      for quality in quality_options:
                          if quality == "Plump":
                              checklist_answers.append(
                                  bing_plump_option
                                  if cherry_type == "Bing"
                                  else king_plump_option
                                  if cherry_type == "King"
                                  else rainier_plump_option
                              )
                          elif quality == "Juicy":
                              checklist_answers.append(
                                  bing_juicy_option
                                  if cherry_type == "Bing"
                                  else king_juicy_option
                                  if cherry_type == "King"
                                  else rainier_juicy_option
                              )
                          elif quality == "Large":
                              checklist_answers.append(
                                  bing_large_option
                                  if cherry_type == "Bing"
                                  else king_large_option
                                  if cherry_type == "King"
                                  else rainier_large_option
                              )

                      if checklist_attribute and checklist_answers:
                          box_object_instance.set_answer(
                              attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                          )

                  else:
                      # Reuse existing instance across frames
                      box_object_instance = object_instances_by_label_ref[label_ref]

                  # Assign the object to the frame and track it
                  box_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

          # Add object instances to label_row **only if they have frames assigned**
          for box_object_instance in object_instances_by_label_ref.values():
              assert isinstance(box_object_instance, ObjectInstance), "Expected ObjectInstance type"
              if box_object_instance.get_annotation_frames():  # Ensures it has at least one frame
                  label_row.add_object_instance(box_object_instance)

          label_rows_to_save.append(label_row)

      # Step 3: Save all label rows using a bundle
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for label_row in label_rows_to_save:
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)
              print(f"Saved label row for {label_row.data_title}")

      print("Labels with cherry type radio buttons, checklist attributes, text labels, and number attributes added for all data units.")
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Rotatable Bounding Box">
    **Basic**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling

    **Advanced**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling
    * Radio button options
    * Checklist options
    * Text input
    * Number input

    **Rotatable Bounding Box Ontology**

    ![Rotatable Bounding Box Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/labels-rbb-persimmons.png)

    <CodeGroup>
      ```python Rotatable Bounding Boxes Images/Videos - Basic expandable theme={"dark"}

      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # 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 Project ID
      BUNDLE_SIZE = 10

      # Data unit titles in your project
      IMAGE_TITLE = "persimmons-001.jpg"
      IMG_GROUP_TITLE = "persimmons-ig"
      IMG_SEQUENCE_TITLE = "persimmons-is"
      VIDEO_TITLE = "persimmons-vid-001.mp4"

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Find rotatable bbox object "Persimmons" in the ontology
      ontology_structure = project.ontology_structure
      rbbox_ontology_object: Object = ontology_structure.get_child_by_title(title="Persimmons", type_=Object)
      assert rbbox_ontology_object is not None, "Rotatable bbox object 'Persimmons' not found in ontology."

      # Initialise label rows
      label_rows = {}
      all_titles = [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in all_titles:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Coordinates for the rotatable bounding box
      rbbox = RotatableBoundingBoxCoordinates(height=0.35, width=0.35, top_left_x=0.1, top_left_y=0.1, theta=25)

      # Create instances and attach to frames
      label_rows_to_save = []

      # 1. One image > annotate frame 0
      image_lr = label_rows.get(IMAGE_TITLE)
      if image_lr is not None:
          inst: ObjectInstance = rbbox_ontology_object.create_instance()
          inst.set_for_frames(coordinates=rbbox, frames=0)
          image_lr.add_object_instance(inst)
          label_rows_to_save.append(image_lr)

      # 2. One image group > annotate frame 0
      img_group_lr = label_rows.get(IMG_GROUP_TITLE)
      if img_group_lr is not None:
          inst: ObjectInstance = rbbox_ontology_object.create_instance()
          inst.set_for_frames(coordinates=rbbox, frames=0)
          img_group_lr.add_object_instance(inst)
          label_rows_to_save.append(img_group_lr)

      # 3. One image sequence > annotate frame 0
      img_sequence_lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if img_sequence_lr is not None:
          inst: ObjectInstance = rbbox_ontology_object.create_instance()
          inst.set_for_frames(coordinates=rbbox, frames=0)
          img_sequence_lr.add_object_instance(inst)
          label_rows_to_save.append(img_sequence_lr)

      # 4 One video > reuse SAME instance across 3 consecutive frames (frames 100, 101, 102)
      video_lr = label_rows.get(VIDEO_TITLE)
      if video_lr is not None:
          inst: ObjectInstance = rbbox_ontology_object.create_instance()
          consecutive_frames = [100, 101, 102]
          for f in consecutive_frames:
              inst.set_for_frames(coordinates=rbbox, frames=f)
          video_lr.add_object_instance(inst)
          label_rows_to_save.append(video_lr)

      # Save label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in label_rows_to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: created one rotatable bounding box on image, image group, image sequence, and 3 video frames.")
      ```

      ```python Rotatable Bounding Boxes Images/Videos - Advanced expandable theme={"dark"}

      # Import dependencies
      from encord import EncordUserClient, Project
      from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates
      from encord.objects.attributes import NumericAttribute

      # User input
      SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
      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"

      # Create radio button attribute for persimmon type
      ontology_structure = project.ontology_structure
      assert ontology_structure is not None, "Ontology structure is missing from the project"

      # Find a bounding box annotation object in the project ontology
      rbbox_ontology_object: Object = ontology_structure.get_child_by_title(title="Persimmons", type_=Object)
      assert rbbox_ontology_object is not None, "Object 'Persimmons' not found in ontology"

      # Get radio attribute for persimmon type
      persimmon_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert persimmon_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

      # Create radio options
      hachiya_option = persimmon_type_radio_attribute.get_child_by_title(type_=Option, title="Hachiya")
      assert hachiya_option is not None, "Option 'Hachiya' not found under 'Type?'"

      fuyu_option = persimmon_type_radio_attribute.get_child_by_title(type_=Option, title="Fuyu")
      assert fuyu_option is not None, "Option 'Fuyu' not found under 'Type?'"

      rjb_option = persimmon_type_radio_attribute.get_child_by_title(type_=Option, title="Rojo Brilliante")
      assert rjb_option is not None, "Option 'Rojo Brilliante' not found under 'Type?'"

      other_persimmon_option = persimmon_type_radio_attribute.get_child_by_title(type_=Option, title="Other persimmon type")
      assert other_persimmon_option is not None, "Option 'Other persimmon type' not found under 'Type?'"

      # Hachiya Qualities
      hachiya_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Hachiya Qualities?"
      )
      assert hachiya_checklist_attribute is not None, "Checklist attribute 'Hachiya Qualities?' not found"

      hachiya_plump_option = hachiya_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert hachiya_plump_option is not None, "Option 'Plump' not found under 'Hachiya Qualities?'"

      hachiya_juicy_option = hachiya_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert hachiya_juicy_option is not None, "Option 'Juicy' not found under 'Hachiya Qualities?'"

      hachiya_large_option = hachiya_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert hachiya_large_option is not None, "Option 'Large' not found under 'Hachiya Qualities?'"

      # Fuyu Qualities
      fuyu_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Fuyu Qualities?")
      assert fuyu_checklist_attribute is not None, "Checklist attribute 'Fuyu Qualities?' not found"

      fuyu_plump_option = fuyu_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert fuyu_plump_option is not None, "Option 'Plump' not found under 'Fuyu Qualities?'"

      fuyu_juicy_option = fuyu_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert fuyu_juicy_option is not None, "Option 'Juicy' not found under 'Fuyu Qualities?'"

      fuyu_large_option = fuyu_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert fuyu_large_option is not None, "Option 'Large' not found under 'Fuyu Qualities?'"

      # Rojo Brilliante Qualities
      rjb_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Rojo Brilliante Qualities?"
      )
      assert rjb_checklist_attribute is not None, "Checklist attribute 'Rojo Brilliante Qualities?' not found"

      rjb_plump_option = rjb_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert rjb_plump_option is not None, "Option 'Plump' not found under 'Rojo Brilliante Qualities?'"

      rjb_juicy_option = rjb_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert rjb_juicy_option is not None, "Option 'Juicy' not found under 'Rojo Brilliante Qualities?'"

      rjb_large_option = rjb_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert rjb_large_option is not None, "Option 'Large' not found under 'Rojo Brilliante Qualities?'"

      # Other persimmon type text input
      other_persimmon_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify persimmon type"
      )
      assert other_persimmon_option_text_attribute is not None, "Text attribute 'Specify persimmon type' not found"

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

      # Dictionary of labels per data unit and per frame with persimmon type specified, including quality options
      video_frame_labels = {
          "persimmons-001.jpg": {
              0: {
                  "label_ref": "persimmon_001",
                  "coordinates": RotatableBoundingBoxCoordinates(
                      height=0.4, width=0.4, top_left_x=0.05, top_left_y=0.55, theta=23
                  ),
                  "persimmon_type": "Rojo Brilliante",
                  "rjb_quality_options": "Plump, Juicy",
                  "quality_number": 6
              },
          },
          "persimmons-010.jpg": {
              0: [
                  {
                      "label_ref": "persimmon_002",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.4, width=0.4, top_left_x=0.05, top_left_y=0.55, theta=23
                      ),
                      "persimmon_type": "Fuyu",
                      "fuyu_quality_options": "Plump, Juicy, Large",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "persimmon_003",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.1, top_left_x=0.2, top_left_y=0.2, theta=25
                      ),
                      "persimmon_type": "Rojo Brilliante",
                      "rjb_quality_options": "Plump",
                      "quality_number": 5
                  },
                  {
                      "label_ref": "persimmon_004",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.1, top_left_x=0.3, top_left_y=0.3, theta=27
                      ),
                      "persimmon_type": "Other persimmon type",
                      "Specify persimmon type": "Triumph",
                      "quality_number": 4
                  },
              ],
          },
          "persimmons-ig": {
              0: {
                  "label_ref": "persimmon_005",
                  "coordinates": RotatableBoundingBoxCoordinates(
                      height=0.4, width=0.4, top_left_x=0.05, top_left_y=0.55, theta=23
                  ),
                  "persimmon_type": "Hachiya",
                  "hachiya_quality_options": "Plump, Juicy",
                  "quality_number": 7
              },
              2: [
                  {
                      "label_ref": "persimmon_006",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.1, width=0.2, top_left_x=0.2, top_left_y=0.2, theta=23
                      ),
                      "persimmon_type": "Fuyu",
                      "fuyu_quality_options": "Large",
                      "quality_number": 8
                  },
                  {
                      "label_ref": "persimmon_007",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.1, width=0.2, top_left_x=0.4, top_left_y=0.2, theta=127
                      ),
                      "persimmon_type": "Rojo Brilliante",
                      "rjb_quality_options": "Plump",
                      "quality_number": 6
                  },
                  {
                      "label_ref": "persimmon_008",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.1, top_left_x=0.6, top_left_y=0.3, theta=137
                      ),
                      "persimmon_type": "Other persimmon type",
                      "Specify persimmon type": "Hiro",
                      "quality_number": 6
                  },
              ],
          },
          "persimmons-is": {
              0: {
                  "label_ref": "persimmon_009",
                  "coordinates": RotatableBoundingBoxCoordinates(
                      height=0.4, width=0.4, top_left_x=0.05, top_left_y=0.55, theta=23
                  ),
                  "persimmon_type": "Hachiya",
                  "hachiya_quality_options": "Plump",
                  "quality_number": 7
              },
              3: [
                  {
                      "label_ref": "persimmon_010",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.4, width=0.4, top_left_x=0.05, top_left_y=0.05, theta=23
                      ),
                      "persimmon_type": "Fuyu",
                      "fuyu_quality_options": "Plump, Juicy, Large",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "persimmon_011",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.3, width=0.3, top_left_x=0.5, top_left_y=0.05, theta=23
                      ),
                      "persimmon_type": "Rojo Brilliante",
                      "rjb_quality_options": "Plump, Juicy",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "persimmon_012",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.1, top_left_x=0.7, top_left_y=0.05, theta=23
                      ),
                      "persimmon_type": "Other persimmon type",
                      "Specify persimmon type": "Maru",
                      "quality_number": 8
                  },
              ],
          },
          "persimmons-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "persimmon_013",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.5, width=0.5, top_left_x=0.05, top_left_y=0.55, theta=23
                      ),
                      "persimmon_type": "Rojo Brilliante",
                      "rjb_quality_options": "Plump",
                      "quality_number": 7
                  },
                  {
                      "label_ref": "persimmon_014",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.2, top_left_x=0.3, top_left_y=0.2, theta=23
                      ),
                      "persimmon_type": "Hachiya",
                      "hachiya_quality_options": "Plump, Juicy, Large",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "persimmon_015",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.1, top_left_x=0.6, top_left_y=0.2, theta=23
                      ),
                      "persimmon_type": "Other persimmon type",
                      "Specify persimmon type": "Triumph",
                      "quality_number": 2
                  },
              ],
              104: [
                  {
                      "label_ref": "persimmon_016",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.5, width=0.5, top_left_x=0.05, top_left_y=0.55, theta=23
                      ),
                      "persimmon_type": "Rojo Brilliante",
                      "rjb_quality_options": "Plump",
                      "quality_number": 5
                  },
                  {
                      "label_ref": "persimmon_014",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.2, top_left_x=0.3, top_left_y=0.2, theta=23
                      ),
                      "persimmon_type": "Hachiya",
                      "hachiya_quality_options": "Plump, Juicy, Large",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "persimmon_017",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.1, top_left_x=0.6, top_left_y=0.2, theta=23
                      ),
                      "persimmon_type": "Other persimmon type",
                      "Specify persimmon type": "Hiro",
                      "quality_number": 4
                  },
              ],
              105: [
                  {
                      "label_ref": "persimmon_016",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.5, width=0.5, top_left_x=0.05, top_left_y=0.55, theta=23
                      ),
                      "persimmon_type": "Rojo Brilliante",
                      "rjb_quality_options": "Plump",
                      "quality_number": 7
                  },
                  {
                      "label_ref": "persimmon_014",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.2, top_left_x=0.3, top_left_y=0.2, theta=23
                      ),
                      "persimmon_type": "Hachiya",
                      "hachiya_quality_options": "Plump, Juicy, Large",
                      "quality_number": 8
                  },
                  {
                      "label_ref": "persimmon_017",
                      "coordinates": RotatableBoundingBoxCoordinates(
                          height=0.2, width=0.1, top_left_x=0.6, top_left_y=0.2, theta=23
                      ),
                      "persimmon_type": "Other persimmon type",
                      "Specify persimmon type": "Maru",
                      "quality_number": 5
                  },
              ],
          },
      }

      # Cache label rows after initialization
      label_row_map = {}

      # Step 1: Initialize all label rows with a bundle
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for data_unit in video_frame_labels.keys():
              label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
              assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"
              assert label_rows, f"No label row found for {data_unit}"

              label_row = label_rows[0]
              assert label_row is not None, f"Label row is None for {data_unit}"

              label_row.initialise_labels(bundle=bundle)
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              label_row_map[data_unit] = label_row  # Cache it for processing later

      # Step 2: Process labels and collect label rows to save
      label_rows_to_save = []

      for data_unit, frame_coordinates in video_frame_labels.items():
          label_row = label_row_map.get(data_unit)
          assert label_row is not None, f"Missing initialized label row for {data_unit}"

          object_instances_by_label_ref = {}

          for frame_number, items in frame_coordinates.items():
              assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"

              if not isinstance(items, list):
                  items = [items]

              for item in items:
                  label_ref = item["label_ref"]
                  coord = item["coordinates"]
                  persimmon_type = item["persimmon_type"]
                  quality_number = item["quality_number"]

                  assert persimmon_type in {
                      "Hachiya",
                      "Fuyu",
                      "Rojo Brilliante",
                      "Other persimmon type",
                  }, f"Unexpected persimmon type '{persimmon_type}' in {data_unit}"

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

                      # Set quality number attribute 
                      rbbox_object_instance.set_answer(attribute=quality_number_attribute, answer=quality_number)

                      checklist_attribute = None
                      quality_options = []

                      # Set persimmon type and checklist attributes
                      if persimmon_type == "Hachiya":
                          assert hachiya_option is not None, "Missing 'hachiya_option'"
                          rbbox_object_instance.set_answer(attribute=persimmon_type_radio_attribute, answer=hachiya_option)
                          checklist_attribute = hachiya_checklist_attribute
                          quality_options = item.get("hachiya_quality_options", "").split(", ")
                      elif persimmon_type == "Fuyu":
                          assert fuyu_option is not None, "Missing 'fuyu_option'"
                          rbbox_object_instance.set_answer(attribute=persimmon_type_radio_attribute, answer=fuyu_option)
                          checklist_attribute = fuyu_checklist_attribute
                          quality_options = item.get("fuyu_quality_options", "").split(", ")
                      elif persimmon_type == "Rojo Brilliante":
                          assert rjb_option is not None, "Missing 'rjb_option'"
                          rbbox_object_instance.set_answer(attribute=persimmon_type_radio_attribute, answer=rjb_option)
                          checklist_attribute = rjb_checklist_attribute
                          quality_options = item.get("rjb_quality_options", "").split(", ")
                      elif persimmon_type == "Other persimmon type":
                          assert other_persimmon_option is not None, "Missing 'other_persimmon_option'"
                          rbbox_object_instance.set_answer(
                              attribute=persimmon_type_radio_attribute, answer=other_persimmon_option
                          )
                          text_answer = item.get("Specify persimmon type", "")
                          assert isinstance(text_answer, str), "'Specify persimmon type' must be a string"
                          rbbox_object_instance.set_answer(
                              attribute=other_persimmon_option_text_attribute, answer=text_answer
                          )
                          quality_options = []

                      # Set checklist answers based on quality options
                      checklist_answers = []
                      for quality in quality_options:
                          option = None
                          if quality == "Plump":
                              option = (
                                  hachiya_plump_option
                                  if persimmon_type == "Hachiya"
                                  else fuyu_plump_option
                                  if persimmon_type == "Fuyu"
                                  else rjb_plump_option
                                  if persimmon_type == "Rojo Brilliante"
                                  else None
                              )
                          elif quality == "Juicy":
                              option = (
                                  hachiya_juicy_option
                                  if persimmon_type == "Hachiya"
                                  else fuyu_juicy_option
                                  if persimmon_type == "Fuyu"
                                  else rjb_juicy_option
                                  if persimmon_type == "Rojo Brilliante"
                                  else None
                              )
                          elif quality == "Large":
                              option = (
                                  hachiya_large_option
                                  if persimmon_type == "Hachiya"
                                  else fuyu_large_option
                                  if persimmon_type == "Fuyu"
                                  else rjb_large_option
                                  if persimmon_type == "Rojo Brilliante"
                                  else None
                              )

                          if option:
                              checklist_answers.append(option)
                          else:
                              assert persimmon_type == "Other persimmon type", (
                                  f"Invalid quality '{quality}' for persimmon type '{persimmon_type}'"
                              )

                      if checklist_attribute and checklist_answers:
                          rbbox_object_instance.set_answer(
                              attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                          )

                      object_instances_by_label_ref[label_ref] = rbbox_object_instance

                  else:
                      rbbox_object_instance = object_instances_by_label_ref[label_ref]

                  # Assign coordinates for this frame
                  rbbox_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

          # Add object instances to label_row **only if they have frames assigned**
          for rbbox_object_instance in object_instances_by_label_ref.values():
              assert isinstance(rbbox_object_instance, ObjectInstance), "Expected ObjectInstance type"
              if rbbox_object_instance.get_annotation_frames():
                  label_row.add_object_instance(rbbox_object_instance)

          # Collect for saving in the next bundle
          label_rows_to_save.append(label_row)

      # Step 3: Save all label rows with a bundle
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for label_row in label_rows_to_save:
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)
              print(f"Saved label row for {label_row.data_title}")

      print("Labels with persimmon type radio buttons, checklist attributes, number attributes, and text labels added for all data units.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Polygons (Advanced)">
    Polygons can have simple and complex shapes, including being enclosed in one another, and encompassing separate regions. In each case the polygon's coordinates are arranged in a different way.

    **Basic**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling

    **Advanced**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling
    * Radio button options
    * Checklist options
    * Text input
    * Number input

    **Polygon Coordinates**

    Specifying coordinates for polygons uses this format:

    <CodeGroup>
      ```python Simple theme={"dark"}

      PolygonCoordinates(polygons=[[[PointCoordinate(x1, y1), PointCoordinate(x2, y2),...]]]

      ```

      ```python Donut theme={"dark"}

      PolygonCoordinates(polygons=
      [
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Outer ring
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Inner ring
          ]
      ]

      ```

      ```python Multiple Polygons theme={"dark"}

      PolygonCoordinates(polygons=
      [
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 1
          ],
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 2
          ],
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 3
          ],

      ]

      ```

      ```python Donut with Object Inside theme={"dark"}

      PolygonCoordinates(polygons=
      [
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Outer ring
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Inner ring
          ],
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon inside
          ],

      ]

      ```
    </CodeGroup>

    **Simple Polygon**

    Import a simple polygon using the recommended method.

    <div>
      <img />
    </div>

    **Donut**

    Import a complex polygon with a hole in it.

    <div>
      <img />
    </div>

    **Multiple Polygons**

    Import a complex polygon that is in multiple parts.

    <div>
      <img />
    </div>

    **Donut with Object Inside**

    Imports a complex polygon that has a hole in it with another polygon inside.

    <div>
      <img />
    </div>

    **Polygons Ontology**

    This ontology applies for all polygon shapes (simple, donut, multiple polygons, donut with object inside).

    ![Polygons Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/labels-polygons-blueberries.png)

    <CodeGroup title="Complex Polygons - Simple">
      ```python Simple - Basic expandable theme={"dark"}

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

      # 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 Project ID
      BUNDLE_SIZE = 10

      # Data unit titles in your Project
      IMAGE_TITLE = "blueberries-001.jpg"
      IMG_GROUP_TITLE = "blueberries-ig"
      IMG_SEQUENCE_TITLE = "blueberries-is"
      VIDEO_TITLE = "blueberries-vid-001.mp4"

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Find the polygon object "Blueberries" in the ontology
      ontology_structure = project.ontology_structure
      polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="Blueberries", type_=Object)
      assert polygon_ontology_object is not None, "Polygon object 'Blueberries' not found in ontology."

      # Initialise label rows
      label_rows = {}
      all_titles = [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in all_titles:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Coordinates: A simple 5-point polygon (single ring)
      poly = PolygonCoordinates(
          polygons=[
              [
                  [
                      PointCoordinate(0.10, 0.10),
                      PointCoordinate(0.20, 0.15),
                      PointCoordinate(0.25, 0.25),
                      PointCoordinate(0.15, 0.30),
                      PointCoordinate(0.08, 0.22),
                  ]
              ]
          ]
      )

      # Create instances and attach to frames
      label_rows_to_save = []

      # 1. One image > annotate frame 0
      image_lr = label_rows.get(IMAGE_TITLE)
      if image_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly, frames=0)
          image_lr.add_object_instance(inst)
          label_rows_to_save.append(image_lr)

      # 2. One image group > annotate frame 0
      img_group_lr = label_rows.get(IMG_GROUP_TITLE)
      if img_group_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly, frames=0)
          img_group_lr.add_object_instance(inst)
          label_rows_to_save.append(img_group_lr)

      # 3. One image sequence > annotate frame 0
      img_sequence_lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if img_sequence_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly, frames=0)
          img_sequence_lr.add_object_instance(inst)
          label_rows_to_save.append(img_sequence_lr)

      # 4. One video > reuse SAME instance across 3 consecutive frames (frames 100, 101, 102)
      video_lr = label_rows.get(VIDEO_TITLE)
      if video_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          consecutive_frames = [100, 101, 102]
          for f in consecutive_frames:
              inst.set_for_frames(coordinates=poly, frames=f)
          video_lr.add_object_instance(inst)
          label_rows_to_save.append(video_lr)

      # Save label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in label_rows_to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: created one polygon on image, image group, image sequence, and 3 video frames.")
      ```

      ```python Simple - Advanced expandable theme={"dark"}

      # 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

      # 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"
      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"

      # Find polygon object for blueberries
      polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="Blueberries", type_=Object)
      assert polygon_ontology_object is not None, "Object 'Blueberries' not found in ontology"

      # Get radio attribute for blueberry type
      blueberry_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert blueberry_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

      # Get radio options
      bluegold_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Bluegold")
      assert bluegold_option is not None, "Option 'Bluegold' not found under radio attribute 'Type?'"

      duke_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Duke")
      assert duke_option is not None, "Option 'Duke' not found under radio attribute 'Type?'"

      blueray_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Blueray")
      assert blueray_option is not None, "Option 'Blueray' not found under radio attribute 'Type?'"

      other_blueberry_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Other blueberry type")
      assert other_blueberry_option is not None, "Option 'Other blueberry type' not found under radio attribute 'Type?'"

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

      # Bluegold Qualities
      bluegold_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Bluegold Qualities?"
      )
      assert bluegold_checklist_attribute is not None, "Checklist attribute 'Bluegold Qualities?' not found"

      bluegold_plump_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert bluegold_plump_option is not None, "Option 'Plump' not found under 'Bluegold Qualities?'"

      bluegold_juicy_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert bluegold_juicy_option is not None, "Option 'Juicy' not found under 'Bluegold Qualities?'"

      bluegold_large_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert bluegold_large_option is not None, "Option 'Large' not found under 'Bluegold Qualities?'"

      # Duke Qualities
      duke_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Duke Qualities?")
      assert duke_checklist_attribute is not None, "Checklist attribute 'Duke Qualities?' not found"

      duke_plump_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert duke_plump_option is not None, "Option 'Plump' not found under 'Duke Qualities?'"

      duke_juicy_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert duke_juicy_option is not None, "Option 'Juicy' not found under 'Duke Qualities?'"

      duke_large_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert duke_large_option is not None, "Option 'Large' not found under 'Duke Qualities?'"

      # Blueray Qualities
      blueray_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Blueray Qualities?"
      )
      assert blueray_checklist_attribute is not None, "Checklist attribute 'Blueray Qualities?' not found"

      blueray_plump_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert blueray_plump_option is not None, "Option 'Plump' not found under 'Blueray Qualities?'"

      blueray_juicy_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert blueray_juicy_option is not None, "Option 'Juicy' not found under 'Blueray Qualities?'"

      blueray_large_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert blueray_large_option is not None, "Option 'Large' not found under 'Blueray Qualities?'"

      # Other blueberry type — text input
      other_blueberry_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify blueberry type"
      )
      assert other_blueberry_option_text_attribute is not None, "Text attribute 'Specify blueberry type' not found"


      # Dictionary of labels per data unit and per frame with blueberry type specified, including quality options
      video_frame_labels = {
          "blueberries-001.jpg": {
              0: {
                  "label_ref": "blueberry_001",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              [
                                  PointCoordinate(0.01, 0.02),
                                  PointCoordinate(0.03, 0.03),
                                  PointCoordinate(0.05, 0.02),
                                  PointCoordinate(0.04, 0.01),
                                  PointCoordinate(0.02, 0.01),
                              ]
                          ]
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                  "blueberry_quality": 8
              }
          },
          "blueberries-010.jpg": {
              0: [
                  {
                      "label_ref": "blueberry_002",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.01, 0.02),
                                      PointCoordinate(0.03, 0.03),
                                      PointCoordinate(0.05, 0.02),
                                      PointCoordinate(0.04, 0.01),
                                      PointCoordinate(0.02, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_003",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.04, 0.05),
                                      PointCoordinate(0.06, 0.06),
                                      PointCoordinate(0.08, 0.05),
                                      PointCoordinate(0.07, 0.04),
                                      PointCoordinate(0.05, 0.04),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_004",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.07, 0.02),
                                      PointCoordinate(0.09, 0.03),
                                      PointCoordinate(0.11, 0.02),
                                      PointCoordinate(0.10, 0.01),
                                      PointCoordinate(0.08, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 3
                  },
              ],
          },
          "blueberries-ig": {
              0: {
                  "label_ref": "blueberry_005",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              [
                                  PointCoordinate(0.01, 0.02),
                                  PointCoordinate(0.03, 0.03),
                                  PointCoordinate(0.05, 0.02),
                                  PointCoordinate(0.04, 0.01),
                                  PointCoordinate(0.02, 0.01),
                              ]
                          ]
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                  "blueberry_quality": 8
              },
              2: [
                  {
                      "label_ref": "blueberry_006",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.01, 0.02),
                                      PointCoordinate(0.03, 0.03),
                                      PointCoordinate(0.05, 0.02),
                                      PointCoordinate(0.04, 0.01),
                                      PointCoordinate(0.02, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Large",
                      "blueberry_quality": 4
                  },
                  {
                      "label_ref": "blueberry_007",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.04, 0.05),
                                      PointCoordinate(0.06, 0.06),
                                      PointCoordinate(0.08, 0.05),
                                      PointCoordinate(0.07, 0.04),
                                      PointCoordinate(0.05, 0.04),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_008",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.07, 0.02),
                                      PointCoordinate(0.09, 0.03),
                                      PointCoordinate(0.11, 0.02),
                                      PointCoordinate(0.10, 0.01),
                                      PointCoordinate(0.08, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 2
                  },
              ],
          },
          "blueberries-is": {
              0: {
                  "label_ref": "blueberry_009",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              [
                                  PointCoordinate(0.01, 0.02),
                                  PointCoordinate(0.03, 0.03),
                                  PointCoordinate(0.05, 0.02),
                                  PointCoordinate(0.04, 0.01),
                                  PointCoordinate(0.02, 0.01),
                              ]
                          ]
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump",
                  "blueberry_quality": 6
              },
              3: [
                  {
                      "label_ref": "blueberry_010",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.01, 0.02),
                                      PointCoordinate(0.03, 0.03),
                                      PointCoordinate(0.05, 0.02),
                                      PointCoordinate(0.04, 0.01),
                                      PointCoordinate(0.02, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_011",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.04, 0.05),
                                      PointCoordinate(0.06, 0.06),
                                      PointCoordinate(0.08, 0.05),
                                      PointCoordinate(0.07, 0.04),
                                      PointCoordinate(0.05, 0.04),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_012",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.07, 0.02),
                                      PointCoordinate(0.09, 0.03),
                                      PointCoordinate(0.11, 0.02),
                                      PointCoordinate(0.10, 0.01),
                                      PointCoordinate(0.08, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 7
                  },
              ],
          },
          "blueberries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "blueberry_013",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.01, 0.02),
                                      PointCoordinate(0.03, 0.03),
                                      PointCoordinate(0.05, 0.02),
                                      PointCoordinate(0.04, 0.01),
                                      PointCoordinate(0.02, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.04, 0.05),
                                      PointCoordinate(0.06, 0.06),
                                      PointCoordinate(0.08, 0.05),
                                      PointCoordinate(0.07, 0.04),
                                      PointCoordinate(0.05, 0.04),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_015",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.07, 0.02),
                                      PointCoordinate(0.09, 0.03),
                                      PointCoordinate(0.11, 0.02),
                                      PointCoordinate(0.10, 0.01),
                                      PointCoordinate(0.08, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 8
                  },
              ],
              104: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.01, 0.02),
                                      PointCoordinate(0.03, 0.03),
                                      PointCoordinate(0.05, 0.02),
                                      PointCoordinate(0.04, 0.01),
                                      PointCoordinate(0.02, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.041, 0.052),
                                      PointCoordinate(0.061, 0.062),
                                      PointCoordinate(0.081, 0.052),
                                      PointCoordinate(0.071, 0.042),
                                      PointCoordinate(0.051, 0.042),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.07, 0.02),
                                      PointCoordinate(0.09, 0.03),
                                      PointCoordinate(0.11, 0.02),
                                      PointCoordinate(0.10, 0.01),
                                      PointCoordinate(0.08, 0.01),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 7
                  },
              ],
              105: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.011, 0.022),
                                      PointCoordinate(0.031, 0.032),
                                      PointCoordinate(0.051, 0.022),
                                      PointCoordinate(0.041, 0.012),
                                      PointCoordinate(0.021, 0.012),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.043, 0.055),
                                      PointCoordinate(0.063, 0.065),
                                      PointCoordinate(0.083, 0.055),
                                      PointCoordinate(0.073, 0.045),
                                      PointCoordinate(0.053, 0.045),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              [
                                  [
                                      PointCoordinate(0.071, 0.022),
                                      PointCoordinate(0.091, 0.032),
                                      PointCoordinate(0.111, 0.022),
                                      PointCoordinate(0.101, 0.012),
                                      PointCoordinate(0.081, 0.012),
                                  ]
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 3
                  },
              ],
          },
      }

      # Loop through each data unit (image, video, etc.)
      for data_unit, frame_coordinates in video_frame_labels.items():
          object_instances_by_label_ref = {}

          # Get the label row for the current data unit
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"
          assert label_rows, f"No label rows found for data unit: {data_unit}"

          label_row = label_rows[0]
          assert label_row is not None, f"Label row is None for {data_unit}"

          # Initialize label row using bundle
          with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
              label_row.initialise_labels()
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              for frame_number, items in frame_coordinates.items():
                  assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"

                  if not isinstance(items, list):  # Single or multiple objects in the frame
                      items = [items]

                  for item in items:
                      label_ref = item["label_ref"]
                      coord = item["coordinates"]
                      blueberry_type = item["blueberry_type"]
                      blueberry_quality = item["blueberry_quality"]

                      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(", ")

                          for quality in quality_options:
                              option = None
                              if quality == "Plump":
                                  option = (
                                      bluegold_plump_option
                                      if blueberry_type == "Bluegold"
                                      else duke_plump_option
                                      if blueberry_type == "Duke"
                                      else blueray_plump_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Juicy":
                                  option = (
                                      bluegold_juicy_option
                                      if blueberry_type == "Bluegold"
                                      else duke_juicy_option
                                      if blueberry_type == "Duke"
                                      else blueray_juicy_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Large":
                                  option = (
                                      bluegold_large_option
                                      if blueberry_type == "Bluegold"
                                      else duke_large_option
                                      if blueberry_type == "Duke"
                                      else blueray_large_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )

                              if option:
                                  checklist_answers.append(option)
                              else:
                                  assert blueberry_type == "Other blueberry type", (
                                      f"Invalid quality '{quality}' for type '{blueberry_type}'"
                                  )

                          if checklist_attribute and checklist_answers:
                              polygon_object_instance.set_answer(
                                  attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                              )

                      else:
                          polygon_object_instance = object_instances_by_label_ref[label_ref]

                      # Assign the object to the frame and track it
                      polygon_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

              # Add object instances to label_row **only if they have frames assigned**
              for polygon_object_instance in object_instances_by_label_ref.values():
                  assert isinstance(polygon_object_instance, ObjectInstance), "Expected ObjectInstance type"
                  if polygon_object_instance.get_annotation_frames():
                      label_row.add_object_instance(polygon_object_instance)

              # Save label row using the bundle
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)

      print("Labels with blueberry type radio buttons, checklist attributes, number classifications, and text labels added for all data units.")

      ```
    </CodeGroup>

    <CodeGroup title="Complex Polygons - Donut">
      ```python Donut expandable theme={"dark"}

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

      # 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 Project ID
      BUNDLE_SIZE = 10

      # Data unit titles in your Project
      IMAGE_TITLE = "blueberries-001.jpg"
      IMG_GROUP_TITLE = "blueberries-ig"
      IMG_SEQUENCE_TITLE = "blueberries-is"
      VIDEO_TITLE = "blueberries-vid-001.mp4"

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Find the polygon object "Blueberries" in the ontology
      ontology_structure = project.ontology_structure
      polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="Blueberries", type_=Object)
      assert polygon_ontology_object is not None, "Polygon object 'Blueberries' not found in ontology."

      # Initialise label rows
      label_rows = {}
      all_titles = [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in all_titles:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Donut polygon coordinates
      outer_ring = [
          PointCoordinate(0.30, 0.30),
          PointCoordinate(0.40, 0.28),
          PointCoordinate(0.50, 0.35),
          PointCoordinate(0.52, 0.48),
          PointCoordinate(0.46, 0.60),
          PointCoordinate(0.36, 0.62),
          PointCoordinate(0.26, 0.55),
          PointCoordinate(0.24, 0.42),
      ]

      inner_ring = [  # hole
          PointCoordinate(0.36, 0.42),
          PointCoordinate(0.42, 0.41),
          PointCoordinate(0.45, 0.48),
          PointCoordinate(0.41, 0.53),
          PointCoordinate(0.34, 0.50),
      ]

      poly_donut = PolygonCoordinates(polygons=[[outer_ring, inner_ring]])

      # Create instances and attach to frames
      label_rows_to_save = []

      # 1. One image > annotate frame 0
      image_lr = label_rows.get(IMAGE_TITLE)
      if image_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly_donut, frames=0)
          image_lr.add_object_instance(inst)
          label_rows_to_save.append(image_lr)

      # 2. One image group > annotate frame 0
      img_group_lr = label_rows.get(IMG_GROUP_TITLE)
      if img_group_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly_donut, frames=0)
          img_group_lr.add_object_instance(inst)
          label_rows_to_save.append(img_group_lr)

      # 3. One image sequence > annotate frame 0
      img_sequence_lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if img_sequence_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly_donut, frames=0)
          img_sequence_lr.add_object_instance(inst)
          label_rows_to_save.append(img_sequence_lr)

      # 4. One video > reuse SAME instance across 3 consecutive frames (frames 100, 101, 102)
      video_lr = label_rows.get(VIDEO_TITLE)
      if video_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          consecutive_frames = [100, 101, 102]
          for f in consecutive_frames:
              inst.set_for_frames(coordinates=poly_donut, frames=f)
          video_lr.add_object_instance(inst)
          label_rows_to_save.append(video_lr)

      # Save label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in label_rows_to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: created one donut polygon on image, image group, image sequence, and 3 video frames.")
      ```

      ```python Donut - Advanced expandable theme={"dark"}

      # 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"

      # Find polygon object for blueberries
      polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="Blueberries", type_=Object)
      assert polygon_ontology_object is not None, "Object 'Blueberries' not found in ontology"

      # Get radio attribute for blueberry type
      blueberry_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert blueberry_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

      # Get radio options
      bluegold_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Bluegold")
      assert bluegold_option is not None, "Option 'Bluegold' not found under radio attribute 'Type?'"

      duke_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Duke")
      assert duke_option is not None, "Option 'Duke' not found under radio attribute 'Type?'"

      blueray_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Blueray")
      assert blueray_option is not None, "Option 'Blueray' not found under radio attribute 'Type?'"

      other_blueberry_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Other blueberry type")
      assert other_blueberry_option is not None, "Option 'Other blueberry type' not found under radio attribute 'Type?'"

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

      # Bluegold Qualities
      bluegold_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Bluegold Qualities?"
      )
      assert bluegold_checklist_attribute is not None, "Checklist attribute 'Bluegold Qualities?' not found"

      bluegold_plump_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert bluegold_plump_option is not None, "Option 'Plump' not found under 'Bluegold Qualities?'"

      bluegold_juicy_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert bluegold_juicy_option is not None, "Option 'Juicy' not found under 'Bluegold Qualities?'"

      bluegold_large_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert bluegold_large_option is not None, "Option 'Large' not found under 'Bluegold Qualities?'"

      # Duke Qualities
      duke_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Duke Qualities?")
      assert duke_checklist_attribute is not None, "Checklist attribute 'Duke Qualities?' not found"

      duke_plump_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert duke_plump_option is not None, "Option 'Plump' not found under 'Duke Qualities?'"

      duke_juicy_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert duke_juicy_option is not None, "Option 'Juicy' not found under 'Duke Qualities?'"

      duke_large_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert duke_large_option is not None, "Option 'Large' not found under 'Duke Qualities?'"

      # Blueray Qualities
      blueray_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Blueray Qualities?"
      )
      assert blueray_checklist_attribute is not None, "Checklist attribute 'Blueray Qualities?' not found"

      blueray_plump_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert blueray_plump_option is not None, "Option 'Plump' not found under 'Blueray Qualities?'"

      blueray_juicy_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert blueray_juicy_option is not None, "Option 'Juicy' not found under 'Blueray Qualities?'"

      blueray_large_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert blueray_large_option is not None, "Option 'Large' not found under 'Blueray Qualities?'"

      # Other blueberry type — text input
      other_blueberry_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify blueberry type"
      )
      assert other_blueberry_option_text_attribute is not None, "Text attribute 'Specify blueberry type' not found"

      # Dictionary of labels per data unit and per frame with blueberry type specified, including quality options
      video_frame_labels = {
          "blueberries-001.jpg": {
              0: {
                  "label_ref": "blueberry_001",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              # Outer ring (example: square)
                              [
                                  PointCoordinate(0.1, 0.1),
                                  PointCoordinate(0.9, 0.1),
                                  PointCoordinate(0.9, 0.9),
                                  PointCoordinate(0.1, 0.9),
                                  PointCoordinate(0.1, 0.1),  # Closing the ring
                              ],
                              # Inner ring (example: smaller square hole)
                              [
                                  PointCoordinate(0.4, 0.4),
                                  PointCoordinate(0.6, 0.4),
                                  PointCoordinate(0.6, 0.6),
                                  PointCoordinate(0.4, 0.6),
                                  PointCoordinate(0.4, 0.4),  # Closing the ring
                              ],
                          ]
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                  "blueberry_quality": 7
              }
          },
          "blueberries-010.jpg": {
              0: [
                  {
                      "label_ref": "blueberry_002",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First donut polygon
                              [
                                  # Outer ring (larger square)
                                  [
                                      PointCoordinate(0.1, 0.1),
                                      PointCoordinate(0.4, 0.1),
                                      PointCoordinate(0.4, 0.4),
                                      PointCoordinate(0.1, 0.4),
                                      PointCoordinate(0.1, 0.1),
                                      # Close the ring
                                  ],
                                  # Inner ring (smaller square hole)
                                  [
                                      PointCoordinate(0.2, 0.2),
                                      PointCoordinate(0.3, 0.2),
                                      PointCoordinate(0.3, 0.3),
                                      PointCoordinate(0.2, 0.3),
                                      PointCoordinate(0.2, 0.2),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 7
                  },
                  {
                      "label_ref": "blueberry_003",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut polygon
                              [
                                  # Outer ring (another larger square, elsewhere)
                                  [
                                      PointCoordinate(0.6, 0.6),
                                      PointCoordinate(0.9, 0.6),
                                      PointCoordinate(0.9, 0.9),
                                      PointCoordinate(0.6, 0.9),
                                      PointCoordinate(0.6, 0.6),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole in the middle)
                                  [
                                      PointCoordinate(0.7, 0.7),
                                      PointCoordinate(0.8, 0.7),
                                      PointCoordinate(0.8, 0.8),
                                      PointCoordinate(0.7, 0.8),
                                      PointCoordinate(0.7, 0.7),  # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 4
                  },
                  {
                      "label_ref": "blueberry_004",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third donut polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.3, 0.6),
                                      PointCoordinate(0.7, 0.6),
                                      PointCoordinate(0.7, 0.9),
                                      PointCoordinate(0.3, 0.9),
                                      PointCoordinate(0.3, 0.6),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole)
                                  [
                                      PointCoordinate(0.4, 0.7),
                                      PointCoordinate(0.6, 0.7),
                                      PointCoordinate(0.6, 0.8),
                                      PointCoordinate(0.4, 0.8),
                                      PointCoordinate(0.4, 0.7),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 6
                  },
              ],
          },
          "blueberries-ig": {
              0: {
                  "label_ref": "blueberry_005",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              # Outer ring (example: square)
                              [
                                  PointCoordinate(0.1, 0.1),
                                  PointCoordinate(0.9, 0.1),
                                  PointCoordinate(0.9, 0.9),
                                  PointCoordinate(0.1, 0.9),
                                  PointCoordinate(0.1, 0.1),  # Closing the ring
                              ],
                              # Inner ring (example: smaller square hole)
                              [
                                  PointCoordinate(0.4, 0.4),
                                  PointCoordinate(0.6, 0.4),
                                  PointCoordinate(0.6, 0.6),
                                  PointCoordinate(0.4, 0.6),
                                  PointCoordinate(0.4, 0.4),  # Closing the ring
                              ],
                          ]
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                  "blueberry_quality": 7
              },
              2: [
                  {
                      "label_ref": "blueberry_006",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First donut polygon
                              [
                                  # Outer ring (larger square)
                                  [
                                      PointCoordinate(0.1, 0.1),
                                      PointCoordinate(0.4, 0.1),
                                      PointCoordinate(0.4, 0.4),
                                      PointCoordinate(0.1, 0.4),
                                      PointCoordinate(0.1, 0.1),
                                      # Close the ring
                                  ],
                                  # Inner ring (smaller square hole)
                                  [
                                      PointCoordinate(0.2, 0.2),
                                      PointCoordinate(0.3, 0.2),
                                      PointCoordinate(0.3, 0.3),
                                      PointCoordinate(0.2, 0.3),
                                      PointCoordinate(0.2, 0.2),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Large",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_007",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut polygon
                              [
                                  # Outer ring (another larger square, elsewhere)
                                  [
                                      PointCoordinate(0.6, 0.6),
                                      PointCoordinate(0.9, 0.6),
                                      PointCoordinate(0.9, 0.9),
                                      PointCoordinate(0.6, 0.9),
                                      PointCoordinate(0.6, 0.6),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole in the middle)
                                  [
                                      PointCoordinate(0.7, 0.7),
                                      PointCoordinate(0.8, 0.7),
                                      PointCoordinate(0.8, 0.8),
                                      PointCoordinate(0.7, 0.8),
                                      PointCoordinate(0.7, 0.7),  # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_008",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third donut polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.3, 0.6),
                                      PointCoordinate(0.7, 0.6),
                                      PointCoordinate(0.7, 0.9),
                                      PointCoordinate(0.3, 0.9),
                                      PointCoordinate(0.3, 0.6),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole)
                                  [
                                      PointCoordinate(0.4, 0.7),
                                      PointCoordinate(0.6, 0.7),
                                      PointCoordinate(0.6, 0.8),
                                      PointCoordinate(0.4, 0.8),
                                      PointCoordinate(0.4, 0.7),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 8
                  },
              ],
          },
          "blueberries-is": {
              0: {
                  "label_ref": "blueberry_009",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              # Outer ring (example: square)
                              [
                                  PointCoordinate(0.1, 0.1),
                                  PointCoordinate(0.9, 0.1),
                                  PointCoordinate(0.9, 0.9),
                                  PointCoordinate(0.1, 0.9),
                                  PointCoordinate(0.1, 0.1),  # Closing the ring
                              ],
                              # Inner ring (example: smaller square hole)
                              [
                                  PointCoordinate(0.4, 0.4),
                                  PointCoordinate(0.6, 0.4),
                                  PointCoordinate(0.6, 0.6),
                                  PointCoordinate(0.4, 0.6),
                                  PointCoordinate(0.4, 0.4),  # Closing the ring
                              ],
                          ]
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump",
                  "blueberry_quality": 8
              },
              3: [
                  {
                      "label_ref": "blueberry_010",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First donut polygon
                              [
                                  # Outer ring (larger square)
                                  [
                                      PointCoordinate(0.1, 0.1),
                                      PointCoordinate(0.4, 0.1),
                                      PointCoordinate(0.4, 0.4),
                                      PointCoordinate(0.1, 0.4),
                                      PointCoordinate(0.1, 0.1),
                                      # Close the ring
                                  ],
                                  # Inner ring (smaller square hole)
                                  [
                                      PointCoordinate(0.2, 0.2),
                                      PointCoordinate(0.3, 0.2),
                                      PointCoordinate(0.3, 0.3),
                                      PointCoordinate(0.2, 0.3),
                                      PointCoordinate(0.2, 0.2),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_011",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut polygon
                              [
                                  # Outer ring (another larger square, elsewhere)
                                  [
                                      PointCoordinate(0.6, 0.6),
                                      PointCoordinate(0.9, 0.6),
                                      PointCoordinate(0.9, 0.9),
                                      PointCoordinate(0.6, 0.9),
                                      PointCoordinate(0.6, 0.6),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole in the middle)
                                  [
                                      PointCoordinate(0.7, 0.7),
                                      PointCoordinate(0.8, 0.7),
                                      PointCoordinate(0.8, 0.8),
                                      PointCoordinate(0.7, 0.8),
                                      PointCoordinate(0.7, 0.7),  # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_012",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third donut polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.3, 0.6),
                                      PointCoordinate(0.7, 0.6),
                                      PointCoordinate(0.7, 0.9),
                                      PointCoordinate(0.3, 0.9),
                                      PointCoordinate(0.3, 0.6),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole)
                                  [
                                      PointCoordinate(0.4, 0.7),
                                      PointCoordinate(0.6, 0.7),
                                      PointCoordinate(0.6, 0.8),
                                      PointCoordinate(0.4, 0.8),
                                      PointCoordinate(0.4, 0.7),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 8
                  },
              ],
          },
          "blueberries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "blueberry_013",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First donut polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.05, 0.55),
                                      PointCoordinate(0.25, 0.55),
                                      PointCoordinate(0.25, 0.75),
                                      PointCoordinate(0.05, 0.75),
                                      PointCoordinate(0.05, 0.55),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole)
                                  [
                                      PointCoordinate(0.10, 0.60),
                                      PointCoordinate(0.20, 0.60),
                                      PointCoordinate(0.20, 0.70),
                                      PointCoordinate(0.10, 0.70),
                                      PointCoordinate(0.10, 0.60),
                                      # Close the ring
                                  ],
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut polygon
                              [
                                  # Outer ring (larger square)
                                  [
                                      PointCoordinate(0.1, 0.1),
                                      PointCoordinate(0.4, 0.1),
                                      PointCoordinate(0.4, 0.4),
                                      PointCoordinate(0.1, 0.4),
                                      PointCoordinate(0.1, 0.1),
                                      # Close the ring
                                  ],
                                  # Inner ring (smaller square hole)
                                  [
                                      PointCoordinate(0.2, 0.2),
                                      PointCoordinate(0.3, 0.2),
                                      PointCoordinate(0.3, 0.3),
                                      PointCoordinate(0.2, 0.3),
                                      PointCoordinate(0.2, 0.2),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                  },
                  {
                      "label_ref": "blueberry_015",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third donut polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.75, 0.75),
                                      PointCoordinate(0.95, 0.75),
                                      PointCoordinate(0.95, 0.95),
                                      PointCoordinate(0.75, 0.95),
                                      PointCoordinate(0.75, 0.75),  # Close the ring
                                  ],
                                  # Inner ring (hole)
                                  [
                                      PointCoordinate(0.80, 0.80),
                                      PointCoordinate(0.90, 0.80),
                                      PointCoordinate(0.90, 0.90),
                                      PointCoordinate(0.80, 0.90),
                                      PointCoordinate(0.80, 0.80),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 4
                  },
              ],
              104: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fourth donut polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.6, 0.1),
                                      PointCoordinate(0.9, 0.1),
                                      PointCoordinate(0.9, 0.4),
                                      PointCoordinate(0.6, 0.4),
                                      PointCoordinate(0.6, 0.1),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole)
                                  [
                                      PointCoordinate(0.7, 0.2),
                                      PointCoordinate(0.8, 0.2),
                                      PointCoordinate(0.8, 0.3),
                                      PointCoordinate(0.7, 0.3),
                                      PointCoordinate(0.7, 0.2),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut polygon
                              [
                                  # Outer ring (larger square)
                                  [
                                      PointCoordinate(0.13, 0.13),
                                      PointCoordinate(0.43, 0.13),
                                      PointCoordinate(0.43, 0.43),
                                      PointCoordinate(0.13, 0.43),
                                      PointCoordinate(0.13, 0.13),
                                      # Close the ring
                                  ],
                                  # Inner ring (smaller square hole)
                                  [
                                      PointCoordinate(0.18, 0.18),
                                      PointCoordinate(0.28, 0.18),
                                      PointCoordinate(0.28, 0.28),
                                      PointCoordinate(0.17, 0.27),
                                      PointCoordinate(0.18, 0.18),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fifth donut polygon
                              [
                                  # Outer ring (larger square)
                                  [
                                      PointCoordinate(0.32, 0.62),
                                      PointCoordinate(0.72, 0.61),
                                      PointCoordinate(0.71, 0.92),
                                      PointCoordinate(0.31, 0.91),
                                      PointCoordinate(0.32, 0.62),
                                      # Close the ring
                                  ],
                                  # Inner ring (smaller square hole)
                                  [
                                      PointCoordinate(0.42, 0.72),
                                      PointCoordinate(0.61, 0.71),
                                      PointCoordinate(0.59, 0.82),
                                      PointCoordinate(0.41, 0.81),
                                      PointCoordinate(0.42, 0.72),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 7
                  },
              ],
              105: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fourth donut polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.62, 0.12),
                                      PointCoordinate(0.91, 0.13),
                                      PointCoordinate(0.89, 0.42),
                                      PointCoordinate(0.61, 0.40),
                                      PointCoordinate(0.62, 0.12),
                                      # Close the ring
                                  ],
                                  # Inner ring (hole)
                                  [
                                      PointCoordinate(0.72, 0.22),
                                      PointCoordinate(0.82, 0.23),
                                      PointCoordinate(0.81, 0.33),
                                      PointCoordinate(0.71, 0.32),
                                      PointCoordinate(0.72, 0.22),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut polygon
                              [
                                  # Outer ring (larger square)
                                  [
                                      PointCoordinate(0.11, 0.14),
                                      PointCoordinate(0.41, 0.13),
                                      PointCoordinate(0.40, 0.44),
                                      PointCoordinate(0.10, 0.42),
                                      PointCoordinate(0.11, 0.14),
                                      # Close the ring
                                  ],
                                  # Inner ring (smaller square hole)
                                  [
                                      PointCoordinate(0.21, 0.24),
                                      PointCoordinate(0.30, 0.23),
                                      PointCoordinate(0.28, 0.34),
                                      PointCoordinate(0.19, 0.32),
                                      PointCoordinate(0.21, 0.24),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fifth donut polygon
                              [
                                  # Outer ring (larger square)
                                  [
                                      PointCoordinate(0.33, 0.60),
                                      PointCoordinate(0.73, 0.59),
                                      PointCoordinate(0.72, 0.88),
                                      PointCoordinate(0.32, 0.89),
                                      PointCoordinate(0.33, 0.60),
                                      # Close the ring
                                  ],
                                  # Inner ring (smaller square hole)
                                  [
                                      PointCoordinate(0.43, 0.70),
                                      PointCoordinate(0.62, 0.69),
                                      PointCoordinate(0.60, 0.80),
                                      PointCoordinate(0.42, 0.79),
                                      PointCoordinate(0.43, 0.70),
                                      # Close the ring
                                  ],
                              ]
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 3
                  },
              ],
          },
      }

      # Loop through each data unit (image, video, etc.)
      for data_unit, frame_coordinates in video_frame_labels.items():
          object_instances_by_label_ref = {}

          # Get the label row for the current data unit
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"
          assert label_rows, f"No label rows found for data unit: {data_unit}"

          label_row = label_rows[0]
          assert label_row is not None, f"Label row is None for {data_unit}"

          # Initialize label row using bundle
          with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
              label_row.initialise_labels()
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              for frame_number, items in frame_coordinates.items():
                  assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"

                  if not isinstance(items, list):  # Single or multiple objects in the frame
                      items = [items]

                  for item in items:
                      label_ref = item["label_ref"]
                      coord = item["coordinates"]
                      blueberry_type = item["blueberry_type"]
                      blueberry_quality = item["blueberry_quality"]

                      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(", ")

                          for quality in quality_options:
                              option = None
                              if quality == "Plump":
                                  option = (
                                      bluegold_plump_option
                                      if blueberry_type == "Bluegold"
                                      else duke_plump_option
                                      if blueberry_type == "Duke"
                                      else blueray_plump_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Juicy":
                                  option = (
                                      bluegold_juicy_option
                                      if blueberry_type == "Bluegold"
                                      else duke_juicy_option
                                      if blueberry_type == "Duke"
                                      else blueray_juicy_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Large":
                                  option = (
                                      bluegold_large_option
                                      if blueberry_type == "Bluegold"
                                      else duke_large_option
                                      if blueberry_type == "Duke"
                                      else blueray_large_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )

                              if option:
                                  checklist_answers.append(option)
                              else:
                                  assert blueberry_type == "Other blueberry type", (
                                      f"Invalid quality '{quality}' for type '{blueberry_type}'"
                                  )

                          if checklist_attribute and checklist_answers:
                              polygon_object_instance.set_answer(
                                  attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                              )

                      else:
                          polygon_object_instance = object_instances_by_label_ref[label_ref]

                      # Assign the object to the frame and track it
                      polygon_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

              # Add object instances to label_row **only if they have frames assigned**
              for polygon_object_instance in object_instances_by_label_ref.values():
                  assert isinstance(polygon_object_instance, ObjectInstance), "Expected ObjectInstance type"
                  if polygon_object_instance.get_annotation_frames():
                      label_row.add_object_instance(polygon_object_instance)

              # Save label row using the bundle
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)

      print("Labels with blueberry type radio buttons, checklist attributes, number attributes, and text labels added for all data units.")

      ```
    </CodeGroup>

    <CodeGroup title="Complex Polygons - Multiple">
      ```python Multiple - Basic expandable theme={"dark"}

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

      # 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 Project ID
      BUNDLE_SIZE = 10

      # Data unit titles in your Project
      IMAGE_TITLE = "blueberries-001.jpg"
      IMG_GROUP_TITLE = "blueberries-ig"
      IMG_SEQUENCE_TITLE = "blueberries-is"
      VIDEO_TITLE = "blueberries-vid-001.mp4"

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Find the polygon object "Blueberries" in the ontology
      ontology_structure = project.ontology_structure
      polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="Blueberries", type_=Object)
      assert polygon_ontology_object is not None, "Polygon object 'Blueberries' not found in ontology."

      # Initialise label rows
      label_rows = {}
      all_titles = [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in all_titles:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Multi-polygon coordinates: Two separate simple polygons
      ring_a = [
          PointCoordinate(0.15, 0.15),
          PointCoordinate(0.22, 0.18),
          PointCoordinate(0.24, 0.25),
          PointCoordinate(0.18, 0.28),
          PointCoordinate(0.12, 0.22),
      ]

      ring_b = [
          PointCoordinate(0.55, 0.35),
          PointCoordinate(0.62, 0.38),
          PointCoordinate(0.66, 0.45),
          PointCoordinate(0.60, 0.50),
          PointCoordinate(0.53, 0.43),
      ]

      poly_multi = PolygonCoordinates(polygons=[[ring_a], [ring_b]])

      # Create instances and attach to frames
      label_rows_to_save = []

      # 1. One image > annotate frame 0
      image_lr = label_rows.get(IMAGE_TITLE)
      if image_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly_multi, frames=0)
          image_lr.add_object_instance(inst)
          label_rows_to_save.append(image_lr)

      # 2. One image group > annotate frame 0
      img_group_lr = label_rows.get(IMG_GROUP_TITLE)
      if img_group_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly_multi, frames=0)
          img_group_lr.add_object_instance(inst)
          label_rows_to_save.append(img_group_lr)

      # 3. One image sequence > annotate frame 0
      img_sequence_lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if img_sequence_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          inst.set_for_frames(coordinates=poly_multi, frames=0)
          img_sequence_lr.add_object_instance(inst)
          label_rows_to_save.append(img_sequence_lr)

      # 4. One video > reuse SAME instance across 3 consecutive frames (frames 100, 101, 102)
      video_lr = label_rows.get(VIDEO_TITLE)
      if video_lr is not None:
          inst: ObjectInstance = polygon_ontology_object.create_instance()
          consecutive_frames = [100, 101, 102]
          for f in consecutive_frames:
              inst.set_for_frames(coordinates=poly_multi, frames=f)
          video_lr.add_object_instance(inst)
          label_rows_to_save.append(video_lr)

      # Save label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in label_rows_to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: created one multi-polygon (two separate rings) on image, image group, image sequence, and 3 video frames.")
      ```

      ```python Multiple - Basic expandable theme={"dark"}

      # 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"

      # Find polygon object for blueberries
      polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="Blueberries", type_=Object)
      assert polygon_ontology_object is not None, "Object 'Blueberries' not found in ontology"

      # Get radio attribute for blueberry type
      blueberry_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert blueberry_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

      # Get radio options
      bluegold_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Bluegold")
      assert bluegold_option is not None, "Option 'Bluegold' not found under radio attribute 'Type?'"

      duke_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Duke")
      assert duke_option is not None, "Option 'Duke' not found under radio attribute 'Type?'"

      blueray_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Blueray")
      assert blueray_option is not None, "Option 'Blueray' not found under radio attribute 'Type?'"

      other_blueberry_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Other blueberry type")
      assert other_blueberry_option is not None, "Option 'Other blueberry type' not found under radio attribute 'Type?'"

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

      # Bluegold Qualities
      bluegold_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Bluegold Qualities?"
      )
      assert bluegold_checklist_attribute is not None, "Checklist attribute 'Bluegold Qualities?' not found"

      bluegold_plump_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert bluegold_plump_option is not None, "Option 'Plump' not found under 'Bluegold Qualities?'"

      bluegold_juicy_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert bluegold_juicy_option is not None, "Option 'Juicy' not found under 'Bluegold Qualities?'"

      bluegold_large_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert bluegold_large_option is not None, "Option 'Large' not found under 'Bluegold Qualities?'"

      # Duke Qualities
      duke_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Duke Qualities?")
      assert duke_checklist_attribute is not None, "Checklist attribute 'Duke Qualities?' not found"

      duke_plump_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert duke_plump_option is not None, "Option 'Plump' not found under 'Duke Qualities?'"

      duke_juicy_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert duke_juicy_option is not None, "Option 'Juicy' not found under 'Duke Qualities?'"

      duke_large_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert duke_large_option is not None, "Option 'Large' not found under 'Duke Qualities?'"

      # Blueray Qualities
      blueray_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Blueray Qualities?"
      )
      assert blueray_checklist_attribute is not None, "Checklist attribute 'Blueray Qualities?' not found"

      blueray_plump_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert blueray_plump_option is not None, "Option 'Plump' not found under 'Blueray Qualities?'"

      blueray_juicy_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert blueray_juicy_option is not None, "Option 'Juicy' not found under 'Blueray Qualities?'"

      blueray_large_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert blueray_large_option is not None, "Option 'Large' not found under 'Blueray Qualities?'"

      # Other blueberry type — text input
      other_blueberry_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify blueberry type"
      )
      assert other_blueberry_option_text_attribute is not None, "Text attribute 'Specify blueberry type' not found"

      # Dictionary of labels per data unit and per frame with blueberry type specified, including quality options
      video_frame_labels = {
          "blueberries-001.jpg": {
              0: {
                  "label_ref": "blueberry_001",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              # Polygon
                              # First part (triangle)
                              [
                                  PointCoordinate(0.1, 0.1),
                                  PointCoordinate(0.3, 0.1),
                                  PointCoordinate(0.2, 0.3),
                                  PointCoordinate(0.1, 0.1),
                                  # Close the polygon
                              ]
                          ],
                          [
                              # Second part (pentagon)
                              [
                                  PointCoordinate(0.6, 0.2),
                                  PointCoordinate(0.7, 0.25),
                                  PointCoordinate(0.75, 0.35),
                                  PointCoordinate(0.65, 0.45),
                                  PointCoordinate(0.55, 0.35),
                                  PointCoordinate(0.6, 0.2),
                                  # Close the polygon
                              ]
                          ],
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                  "blueberry_quality": 8
              }
          },
          "blueberries-010.jpg": {
              0: [
                  {
                      "label_ref": "blueberry_002",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Polygon 1
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.1, 0.1),
                                      PointCoordinate(0.3, 0.1),
                                      PointCoordinate(0.2, 0.3),
                                      PointCoordinate(0.1, 0.1),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.5, 0.5),
                                      PointCoordinate(0.7, 0.5),
                                      PointCoordinate(0.6, 0.7),
                                      PointCoordinate(0.5, 0.5),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_003",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Polygon 2
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.15, 0.6),
                                      PointCoordinate(0.35, 0.6),
                                      PointCoordinate(0.35, 0.8),
                                      PointCoordinate(0.15, 0.8),
                                      PointCoordinate(0.15, 0.6),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.55, 0.15),
                                      PointCoordinate(0.75, 0.15),
                                      PointCoordinate(0.75, 0.35),
                                      PointCoordinate(0.55, 0.35),
                                      PointCoordinate(0.55, 0.15),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_004",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.25, 0.25),
                                      PointCoordinate(0.4, 0.3),
                                      PointCoordinate(0.35, 0.45),
                                      PointCoordinate(0.2, 0.4),
                                      PointCoordinate(0.25, 0.25),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.65, 0.6),
                                      PointCoordinate(0.8, 0.65),
                                      PointCoordinate(0.75, 0.8),
                                      PointCoordinate(0.6, 0.75),
                                      PointCoordinate(0.65, 0.6),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 4
                  },
              ],
          },
          "blueberries-ig": {
              0: {
                  "label_ref": "blueberry_005",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              # Polygon
                              # First part (triangle)
                              [
                                  PointCoordinate(0.1, 0.1),
                                  PointCoordinate(0.3, 0.1),
                                  PointCoordinate(0.2, 0.3),
                                  PointCoordinate(0.1, 0.1),
                                  # Close the ring
                              ]
                          ],
                          [
                              # Second part (pentagon)
                              [
                                  PointCoordinate(0.6, 0.2),
                                  PointCoordinate(0.7, 0.25),
                                  PointCoordinate(0.75, 0.35),
                                  PointCoordinate(0.65, 0.45),
                                  PointCoordinate(0.55, 0.35),
                                  PointCoordinate(0.6, 0.2),
                                  # Close the ring
                              ]
                          ],
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                  "blueberry_quality": 7
              },
              2: [
                  {
                      "label_ref": "blueberry_006",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.05, 0.15),
                                      PointCoordinate(0.20, 0.10),
                                      PointCoordinate(0.25, 0.25),
                                      PointCoordinate(0.10, 0.30),
                                      PointCoordinate(0.05, 0.15),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.50, 0.20),
                                      PointCoordinate(0.65, 0.25),
                                      PointCoordinate(0.60, 0.40),
                                      PointCoordinate(0.45, 0.35),
                                      PointCoordinate(0.50, 0.20),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Large",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_007",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.30, 0.60),
                                      PointCoordinate(0.50, 0.60),
                                      PointCoordinate(0.50, 0.75),
                                      PointCoordinate(0.30, 0.75),
                                      PointCoordinate(0.30, 0.60),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.65, 0.55),
                                      PointCoordinate(0.85, 0.55),
                                      PointCoordinate(0.85, 0.70),
                                      PointCoordinate(0.65, 0.70),
                                      PointCoordinate(0.65, 0.55),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_008",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.10, 0.80),
                                      PointCoordinate(0.25, 0.85),
                                      PointCoordinate(0.20, 0.95),
                                      PointCoordinate(0.05, 0.90),
                                      PointCoordinate(0.10, 0.80),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.55, 0.75),
                                      PointCoordinate(0.70, 0.80),
                                      PointCoordinate(0.65, 0.95),
                                      PointCoordinate(0.50, 0.90),
                                      PointCoordinate(0.55, 0.75),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 7
                  },
              ],
          },
          "blueberries-is": {
              0: {
                  "label_ref": "blueberry_009",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          [
                              # Polygon
                              # First part (triangle)
                              [
                                  PointCoordinate(0.1, 0.1),
                                  PointCoordinate(0.3, 0.1),
                                  PointCoordinate(0.2, 0.3),
                                  PointCoordinate(0.1, 0.1),
                                  # Close the ring
                              ]
                          ],
                          [
                              # Second part (pentagon)
                              [
                                  PointCoordinate(0.6, 0.2),
                                  PointCoordinate(0.7, 0.25),
                                  PointCoordinate(0.75, 0.35),
                                  PointCoordinate(0.65, 0.45),
                                  PointCoordinate(0.55, 0.35),
                                  PointCoordinate(0.6, 0.2),
                                  # Close the ring
                              ]
                          ],
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump",
                  "blueberry_quality": 5
              },
              3: [
                  {
                      "label_ref": "blueberry_010",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.05, 0.15),
                                      PointCoordinate(0.20, 0.10),
                                      PointCoordinate(0.25, 0.25),
                                      PointCoordinate(0.10, 0.30),
                                      PointCoordinate(0.05, 0.15),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.50, 0.20),
                                      PointCoordinate(0.65, 0.25),
                                      PointCoordinate(0.60, 0.40),
                                      PointCoordinate(0.45, 0.35),
                                      PointCoordinate(0.50, 0.20),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_011",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.30, 0.60),
                                      PointCoordinate(0.50, 0.60),
                                      PointCoordinate(0.50, 0.75),
                                      PointCoordinate(0.30, 0.75),
                                      PointCoordinate(0.30, 0.60),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.65, 0.55),
                                      PointCoordinate(0.85, 0.55),
                                      PointCoordinate(0.85, 0.70),
                                      PointCoordinate(0.65, 0.70),
                                      PointCoordinate(0.65, 0.55),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 4
                  },
                  {
                      "label_ref": "blueberry_012",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.10, 0.80),
                                      PointCoordinate(0.25, 0.85),
                                      PointCoordinate(0.20, 0.95),
                                      PointCoordinate(0.05, 0.90),
                                      PointCoordinate(0.10, 0.80),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.55, 0.75),
                                      PointCoordinate(0.70, 0.80),
                                      PointCoordinate(0.65, 0.95),
                                      PointCoordinate(0.50, 0.90),
                                      PointCoordinate(0.55, 0.75),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 1
                  },
              ],
          },
          "blueberries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "blueberry_013",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.05, 0.35),
                                      PointCoordinate(0.15, 0.33),
                                      PointCoordinate(0.17, 0.43),
                                      PointCoordinate(0.07, 0.45),
                                      PointCoordinate(0.05, 0.35),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.80, 0.40),
                                      PointCoordinate(0.90, 0.42),
                                      PointCoordinate(0.88, 0.52),
                                      PointCoordinate(0.78, 0.50),
                                      PointCoordinate(0.80, 0.40),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.05, 0.05),
                                      PointCoordinate(0.15, 0.05),
                                      PointCoordinate(0.15, 0.10),
                                      PointCoordinate(0.05, 0.10),
                                      PointCoordinate(0.05, 0.05),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.80, 0.05),
                                      PointCoordinate(0.95, 0.05),
                                      PointCoordinate(0.95, 0.10),
                                      PointCoordinate(0.80, 0.10),
                                      PointCoordinate(0.80, 0.05),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_015",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.15, 0.40),
                                      PointCoordinate(0.25, 0.38),
                                      PointCoordinate(0.27, 0.48),
                                      PointCoordinate(0.17, 0.50),
                                      PointCoordinate(0.15, 0.40),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.65, 0.65),
                                      PointCoordinate(0.75, 0.63),
                                      PointCoordinate(0.77, 0.73),
                                      PointCoordinate(0.67, 0.75),
                                      PointCoordinate(0.65, 0.65),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 7
                  },
              ],
              104: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fourth polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.20, 0.20),
                                      PointCoordinate(0.30, 0.18),
                                      PointCoordinate(0.32, 0.28),
                                      PointCoordinate(0.22, 0.30),
                                      PointCoordinate(0.20, 0.20),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.65, 0.20),
                                      PointCoordinate(0.75, 0.22),
                                      PointCoordinate(0.73, 0.32),
                                      PointCoordinate(0.63, 0.30),
                                      PointCoordinate(0.65, 0.20),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.30, 0.60),
                                      PointCoordinate(0.50, 0.60),
                                      PointCoordinate(0.50, 0.75),
                                      PointCoordinate(0.30, 0.75),
                                      PointCoordinate(0.30, 0.60),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.65, 0.55),
                                      PointCoordinate(0.85, 0.55),
                                      PointCoordinate(0.85, 0.70),
                                      PointCoordinate(0.65, 0.70),
                                      PointCoordinate(0.65, 0.55),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fifth polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.05, 0.05),
                                      PointCoordinate(0.15, 0.05),
                                      PointCoordinate(0.15, 0.10),
                                      PointCoordinate(0.05, 0.10),
                                      PointCoordinate(0.05, 0.05),
                                      # Close the polygon
                                  ]
                              ],
                              [
                                  # Second part
                                  [
                                      PointCoordinate(0.80, 0.05),
                                      PointCoordinate(0.95, 0.05),
                                      PointCoordinate(0.95, 0.10),
                                      PointCoordinate(0.80, 0.10),
                                      PointCoordinate(0.80, 0.05),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 8
                  },
              ],
              105: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fourth polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.40, 0.40),
                                      PointCoordinate(0.50, 0.40),
                                      PointCoordinate(0.50, 0.50),
                                      PointCoordinate(0.40, 0.50),
                                      PointCoordinate(0.40, 0.40),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.55, 0.55),
                                      PointCoordinate(0.65, 0.55),
                                      PointCoordinate(0.65, 0.65),
                                      PointCoordinate(0.55, 0.65),
                                      PointCoordinate(0.55, 0.55),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.10, 0.80),
                                      PointCoordinate(0.25, 0.85),
                                      PointCoordinate(0.20, 0.95),
                                      PointCoordinate(0.05, 0.90),
                                      PointCoordinate(0.10, 0.80),
                                      # Close the polygon
                                  ]
                              ],
                              # Second part
                              [
                                  [
                                      PointCoordinate(0.55, 0.75),
                                      PointCoordinate(0.70, 0.80),
                                      PointCoordinate(0.65, 0.95),
                                      PointCoordinate(0.50, 0.90),
                                      PointCoordinate(0.55, 0.75),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 8
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fifth polygon
                              [
                                  # First part
                                  [
                                      PointCoordinate(0.35, 0.05),
                                      PointCoordinate(0.45, 0.05),
                                      PointCoordinate(0.45, 0.15),
                                      PointCoordinate(0.35, 0.15),
                                      PointCoordinate(0.35, 0.05),
                                      # Close the polygon
                                  ]
                              ],
                              [
                                  # Second part
                                  [
                                      PointCoordinate(0.55, 0.05),
                                      PointCoordinate(0.65, 0.05),
                                      PointCoordinate(0.65, 0.15),
                                      PointCoordinate(0.55, 0.15),
                                      PointCoordinate(0.55, 0.05),
                                      # Close the polygon
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 9
                  },
              ],
          },
      }

      # Loop through each data unit (image, video, etc.)
      for data_unit, frame_coordinates in video_frame_labels.items():
          object_instances_by_label_ref = {}

          # Get the label row for the current data unit
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"
          assert label_rows, f"No label rows found for data unit: {data_unit}"

          label_row = label_rows[0]
          assert label_row is not None, f"Label row is None for {data_unit}"

          # Initialize label row using bundle
          with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
              label_row.initialise_labels()
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              for frame_number, items in frame_coordinates.items():
                  assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"

                  if not isinstance(items, list):  # Single or multiple objects in the frame
                      items = [items]

                  for item in items:
                      label_ref = item["label_ref"]
                      coord = item["coordinates"]
                      blueberry_type = item["blueberry_type"]
                      blueberry_quality = item["blueberry_quality"]

                      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(", ")

                          for quality in quality_options:
                              option = None
                              if quality == "Plump":
                                  option = (
                                      bluegold_plump_option
                                      if blueberry_type == "Bluegold"
                                      else duke_plump_option
                                      if blueberry_type == "Duke"
                                      else blueray_plump_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Juicy":
                                  option = (
                                      bluegold_juicy_option
                                      if blueberry_type == "Bluegold"
                                      else duke_juicy_option
                                      if blueberry_type == "Duke"
                                      else blueray_juicy_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Large":
                                  option = (
                                      bluegold_large_option
                                      if blueberry_type == "Bluegold"
                                      else duke_large_option
                                      if blueberry_type == "Duke"
                                      else blueray_large_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )

                              if option:
                                  checklist_answers.append(option)
                              else:
                                  assert blueberry_type == "Other blueberry type", (
                                      f"Invalid quality '{quality}' for type '{blueberry_type}'"
                                  )

                          if checklist_attribute and checklist_answers:
                              polygon_object_instance.set_answer(
                                  attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                              )

                      else:
                          polygon_object_instance = object_instances_by_label_ref[label_ref]

                      # Assign the object to the frame and track it
                      polygon_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

              # Add object instances to label_row **only if they have frames assigned**
              for polygon_object_instance in object_instances_by_label_ref.values():
                  assert isinstance(polygon_object_instance, ObjectInstance), "Expected ObjectInstance type"
                  if polygon_object_instance.get_annotation_frames():
                      label_row.add_object_instance(polygon_object_instance)

              # Save label row using the bundle
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)

      print("Labels with blueberry type radio buttons, checklist attributes, number classifications and text labels added for all data units.")

      ```
    </CodeGroup>

    <CodeGroup title="Complex Polygons - Donut plus Object">
      <LabelPolygonsImagesVideosExampleBasicDonutPlusObject />

      ```python Donut with Object - Advanced expandable theme={"dark"}

      # 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"

      # Find polygon object for blueberries
      polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="Blueberries", type_=Object)
      assert polygon_ontology_object is not None, "Object 'Blueberries' not found in ontology"

      # Get radio attribute for blueberry type
      blueberry_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert blueberry_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

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

      # Get radio options
      bluegold_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Bluegold")
      assert bluegold_option is not None, "Option 'Bluegold' not found under radio attribute 'Type?'"

      duke_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Duke")
      assert duke_option is not None, "Option 'Duke' not found under radio attribute 'Type?'"

      blueray_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Blueray")
      assert blueray_option is not None, "Option 'Blueray' not found under radio attribute 'Type?'"

      other_blueberry_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Other blueberry type")
      assert other_blueberry_option is not None, "Option 'Other blueberry type' not found under radio attribute 'Type?'"

      # Bluegold Qualities
      bluegold_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Bluegold Qualities?"
      )
      assert bluegold_checklist_attribute is not None, "Checklist attribute 'Bluegold Qualities?' not found"

      bluegold_plump_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert bluegold_plump_option is not None, "Option 'Plump' not found under 'Bluegold Qualities?'"

      bluegold_juicy_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert bluegold_juicy_option is not None, "Option 'Juicy' not found under 'Bluegold Qualities?'"

      bluegold_large_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert bluegold_large_option is not None, "Option 'Large' not found under 'Bluegold Qualities?'"

      # Duke Qualities
      duke_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Duke Qualities?")
      assert duke_checklist_attribute is not None, "Checklist attribute 'Duke Qualities?' not found"

      duke_plump_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert duke_plump_option is not None, "Option 'Plump' not found under 'Duke Qualities?'"

      duke_juicy_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert duke_juicy_option is not None, "Option 'Juicy' not found under 'Duke Qualities?'"

      duke_large_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert duke_large_option is not None, "Option 'Large' not found under 'Duke Qualities?'"

      # Blueray Qualities
      blueray_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Blueray Qualities?"
      )
      assert blueray_checklist_attribute is not None, "Checklist attribute 'Blueray Qualities?' not found"

      blueray_plump_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert blueray_plump_option is not None, "Option 'Plump' not found under 'Blueray Qualities?'"

      blueray_juicy_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert blueray_juicy_option is not None, "Option 'Juicy' not found under 'Blueray Qualities?'"

      blueray_large_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert blueray_large_option is not None, "Option 'Large' not found under 'Blueray Qualities?'"

      # Other blueberry type — text input
      other_blueberry_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify blueberry type"
      )
      assert other_blueberry_option_text_attribute is not None, "Text attribute 'Specify blueberry type' not found"

      # Dictionary of labels per data unit and per frame with blueberry type specified, including quality options
      video_frame_labels = {
          "blueberries-001.jpg": {
              0: {
                  "label_ref": "blueberry_001",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          # Donut + inner polygon
                          [
                              # Outer ring
                              [
                                  PointCoordinate(0.10, 0.10),
                                  PointCoordinate(0.22, 0.09),
                                  PointCoordinate(0.21, 0.22),
                                  PointCoordinate(0.09, 0.21),
                                  PointCoordinate(0.10, 0.10),
                              ],
                              # Inner ring
                              [
                                  PointCoordinate(0.13, 0.13),
                                  PointCoordinate(0.13, 0.18),
                                  PointCoordinate(0.18, 0.18),
                                  PointCoordinate(0.18, 0.13),
                                  PointCoordinate(0.13, 0.13),
                              ],
                          ],
                          # Shape inside the hole
                          [
                              [
                                  PointCoordinate(0.145, 0.145),
                                  PointCoordinate(0.165, 0.150),
                                  PointCoordinate(0.160, 0.165),
                                  PointCoordinate(0.145, 0.145),
                              ]
                          ],
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                   "blueberry_quality": 7
              }
          },
          "blueberries-010.jpg": {
              0: [
                  {
                      "label_ref": "blueberry_002",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.10, 0.10),
                                      PointCoordinate(0.22, 0.09),
                                      PointCoordinate(0.21, 0.22),
                                      PointCoordinate(0.09, 0.21),
                                      PointCoordinate(0.10, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.13, 0.13),
                                      PointCoordinate(0.13, 0.18),
                                      PointCoordinate(0.18, 0.18),
                                      PointCoordinate(0.18, 0.13),
                                      PointCoordinate(0.13, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.145, 0.145),
                                      PointCoordinate(0.165, 0.150),
                                      PointCoordinate(0.160, 0.165),
                                      PointCoordinate(0.145, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                       "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_003",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.30, 0.10),
                                      PointCoordinate(0.42, 0.11),
                                      PointCoordinate(0.41, 0.22),
                                      PointCoordinate(0.29, 0.21),
                                      PointCoordinate(0.30, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.33, 0.13),
                                      PointCoordinate(0.33, 0.18),
                                      PointCoordinate(0.38, 0.18),
                                      PointCoordinate(0.38, 0.13),
                                      PointCoordinate(0.33, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.345, 0.145),
                                      PointCoordinate(0.355, 0.155),
                                      PointCoordinate(0.350, 0.165),
                                      PointCoordinate(0.340, 0.160),
                                      PointCoordinate(0.345, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                       "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_004",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.10, 0.30),
                                      PointCoordinate(0.22, 0.29),
                                      PointCoordinate(0.21, 0.42),
                                      PointCoordinate(0.09, 0.41),
                                      PointCoordinate(0.10, 0.30),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.13, 0.33),
                                      PointCoordinate(0.13, 0.38),
                                      PointCoordinate(0.18, 0.38),
                                      PointCoordinate(0.18, 0.33),
                                      PointCoordinate(0.13, 0.33),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.145, 0.345),
                                      PointCoordinate(0.155, 0.355),
                                      PointCoordinate(0.150, 0.370),
                                      PointCoordinate(0.140, 0.360),
                                      PointCoordinate(0.145, 0.345),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                       "blueberry_quality": 3
                  },
              ],
          },
          "blueberries-ig": {
              0: {
                  "label_ref": "blueberry_005",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          # Donut + inner polygon
                          [
                              # Outer ring
                              [
                                  PointCoordinate(0.10, 0.10),
                                  PointCoordinate(0.22, 0.09),
                                  PointCoordinate(0.21, 0.22),
                                  PointCoordinate(0.09, 0.21),
                                  PointCoordinate(0.10, 0.10),
                              ],
                              # Inner ring
                              [
                                  PointCoordinate(0.13, 0.13),
                                  PointCoordinate(0.13, 0.18),
                                  PointCoordinate(0.18, 0.18),
                                  PointCoordinate(0.18, 0.13),
                                  PointCoordinate(0.13, 0.13),
                              ],
                          ],
                          # Shape inside the hole
                          [
                              [
                                  PointCoordinate(0.145, 0.145),
                                  PointCoordinate(0.165, 0.150),
                                  PointCoordinate(0.160, 0.165),
                                  PointCoordinate(0.145, 0.145),
                              ]
                          ],
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                   "blueberry_quality": 7
              },
              2: [
                  {
                      "label_ref": "blueberry_006",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.10, 0.10),
                                      PointCoordinate(0.22, 0.09),
                                      PointCoordinate(0.21, 0.22),
                                      PointCoordinate(0.09, 0.21),
                                      PointCoordinate(0.10, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.13, 0.13),
                                      PointCoordinate(0.13, 0.18),
                                      PointCoordinate(0.18, 0.18),
                                      PointCoordinate(0.18, 0.13),
                                      PointCoordinate(0.13, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.145, 0.145),
                                      PointCoordinate(0.165, 0.150),
                                      PointCoordinate(0.160, 0.165),
                                      PointCoordinate(0.145, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Large",
                       "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_007",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.30, 0.10),
                                      PointCoordinate(0.42, 0.11),
                                      PointCoordinate(0.41, 0.22),
                                      PointCoordinate(0.29, 0.21),
                                      PointCoordinate(0.30, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.33, 0.13),
                                      PointCoordinate(0.33, 0.18),
                                      PointCoordinate(0.38, 0.18),
                                      PointCoordinate(0.38, 0.13),
                                      PointCoordinate(0.33, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.345, 0.145),
                                      PointCoordinate(0.355, 0.155),
                                      PointCoordinate(0.350, 0.165),
                                      PointCoordinate(0.340, 0.160),
                                      PointCoordinate(0.345, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                       "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_008",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.10, 0.30),
                                      PointCoordinate(0.22, 0.29),
                                      PointCoordinate(0.21, 0.42),
                                      PointCoordinate(0.09, 0.41),
                                      PointCoordinate(0.10, 0.30),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.13, 0.33),
                                      PointCoordinate(0.13, 0.38),
                                      PointCoordinate(0.18, 0.38),
                                      PointCoordinate(0.18, 0.33),
                                      PointCoordinate(0.13, 0.33),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.145, 0.345),
                                      PointCoordinate(0.155, 0.355),
                                      PointCoordinate(0.150, 0.370),
                                      PointCoordinate(0.140, 0.360),
                                      PointCoordinate(0.145, 0.345),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                       "blueberry_quality": 3
                  },
              ],
          },
          "blueberries-is": {
              0: {
                  "label_ref": "blueberry_009",
                  "coordinates": PolygonCoordinates(
                      polygons=[
                          # Donut + inner polygon
                          [
                              # Outer ring
                              [
                                  PointCoordinate(0.10, 0.10),
                                  PointCoordinate(0.22, 0.09),
                                  PointCoordinate(0.21, 0.22),
                                  PointCoordinate(0.09, 0.21),
                                  PointCoordinate(0.10, 0.10),
                              ],
                              # Inner ring
                              [
                                  PointCoordinate(0.13, 0.13),
                                  PointCoordinate(0.13, 0.18),
                                  PointCoordinate(0.18, 0.18),
                                  PointCoordinate(0.18, 0.13),
                                  PointCoordinate(0.13, 0.13),
                              ],
                          ],
                          # Shape inside the hole
                          [
                              [
                                  PointCoordinate(0.145, 0.145),
                                  PointCoordinate(0.165, 0.150),
                                  PointCoordinate(0.160, 0.165),
                                  PointCoordinate(0.145, 0.145),
                              ]
                          ],
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump",
                   "blueberry_quality": 4
              },
              3: [
                  {
                      "label_ref": "blueberry_010",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.10, 0.10),
                                      PointCoordinate(0.22, 0.09),
                                      PointCoordinate(0.21, 0.22),
                                      PointCoordinate(0.09, 0.21),
                                      PointCoordinate(0.10, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.13, 0.13),
                                      PointCoordinate(0.13, 0.18),
                                      PointCoordinate(0.18, 0.18),
                                      PointCoordinate(0.18, 0.13),
                                      PointCoordinate(0.13, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.145, 0.145),
                                      PointCoordinate(0.165, 0.150),
                                      PointCoordinate(0.160, 0.165),
                                      PointCoordinate(0.145, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                       "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_011",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.30, 0.10),
                                      PointCoordinate(0.42, 0.11),
                                      PointCoordinate(0.41, 0.22),
                                      PointCoordinate(0.29, 0.21),
                                      PointCoordinate(0.30, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.33, 0.13),
                                      PointCoordinate(0.33, 0.18),
                                      PointCoordinate(0.38, 0.18),
                                      PointCoordinate(0.38, 0.13),
                                      PointCoordinate(0.33, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.345, 0.145),
                                      PointCoordinate(0.355, 0.155),
                                      PointCoordinate(0.350, 0.165),
                                      PointCoordinate(0.340, 0.160),
                                      PointCoordinate(0.345, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                       "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_012",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.10, 0.30),
                                      PointCoordinate(0.22, 0.29),
                                      PointCoordinate(0.21, 0.42),
                                      PointCoordinate(0.09, 0.41),
                                      PointCoordinate(0.10, 0.30),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.13, 0.33),
                                      PointCoordinate(0.13, 0.38),
                                      PointCoordinate(0.18, 0.38),
                                      PointCoordinate(0.18, 0.33),
                                      PointCoordinate(0.13, 0.33),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.145, 0.345),
                                      PointCoordinate(0.155, 0.355),
                                      PointCoordinate(0.150, 0.370),
                                      PointCoordinate(0.140, 0.360),
                                      PointCoordinate(0.145, 0.345),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                       "blueberry_quality": 5
                  },
              ],
          },
          "blueberries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "blueberry_013",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # First donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.10, 0.10),
                                      PointCoordinate(0.22, 0.09),
                                      PointCoordinate(0.21, 0.22),
                                      PointCoordinate(0.09, 0.21),
                                      PointCoordinate(0.10, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.13, 0.13),
                                      PointCoordinate(0.13, 0.18),
                                      PointCoordinate(0.18, 0.18),
                                      PointCoordinate(0.18, 0.13),
                                      PointCoordinate(0.13, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.145, 0.145),
                                      PointCoordinate(0.165, 0.150),
                                      PointCoordinate(0.160, 0.165),
                                      PointCoordinate(0.145, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                       "blueberry_quality": 4
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.30, 0.10),
                                      PointCoordinate(0.42, 0.11),
                                      PointCoordinate(0.41, 0.22),
                                      PointCoordinate(0.29, 0.21),
                                      PointCoordinate(0.30, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.33, 0.13),
                                      PointCoordinate(0.33, 0.18),
                                      PointCoordinate(0.38, 0.18),
                                      PointCoordinate(0.38, 0.13),
                                      PointCoordinate(0.33, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.345, 0.145),
                                      PointCoordinate(0.355, 0.155),
                                      PointCoordinate(0.350, 0.165),
                                      PointCoordinate(0.340, 0.160),
                                      PointCoordinate(0.345, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                       "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_015",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Third donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.10, 0.30),
                                      PointCoordinate(0.22, 0.29),
                                      PointCoordinate(0.21, 0.42),
                                      PointCoordinate(0.09, 0.41),
                                      PointCoordinate(0.10, 0.30),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.13, 0.33),
                                      PointCoordinate(0.13, 0.38),
                                      PointCoordinate(0.18, 0.38),
                                      PointCoordinate(0.18, 0.33),
                                      PointCoordinate(0.13, 0.33),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.145, 0.345),
                                      PointCoordinate(0.155, 0.355),
                                      PointCoordinate(0.150, 0.370),
                                      PointCoordinate(0.140, 0.360),
                                      PointCoordinate(0.145, 0.345),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 8
                  },
              ],
              104: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fourth donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.30, 0.30),
                                      PointCoordinate(0.42, 0.31),
                                      PointCoordinate(0.41, 0.42),
                                      PointCoordinate(0.29, 0.41),
                                      PointCoordinate(0.30, 0.30),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.33, 0.33),
                                      PointCoordinate(0.33, 0.38),
                                      PointCoordinate(0.38, 0.38),
                                      PointCoordinate(0.38, 0.33),
                                      PointCoordinate(0.33, 0.33),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.345, 0.345),
                                      PointCoordinate(0.360, 0.350),
                                      PointCoordinate(0.355, 0.365),
                                      PointCoordinate(0.345, 0.345),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                       "blueberry_quality": 7
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.31, 0.10),
                                      PointCoordinate(0.45, 0.12),
                                      PointCoordinate(0.43, 0.25),
                                      PointCoordinate(0.30, 0.22),
                                      PointCoordinate(0.31, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.34, 0.14),
                                      PointCoordinate(0.34, 0.19),
                                      PointCoordinate(0.39, 0.20),
                                      PointCoordinate(0.40, 0.15),
                                      PointCoordinate(0.34, 0.14),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.355, 0.155),
                                      PointCoordinate(0.370, 0.160),
                                      PointCoordinate(0.365, 0.175),
                                      PointCoordinate(0.350, 0.170),
                                      PointCoordinate(0.355, 0.155),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                       "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fifth donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.50, 0.10),
                                      PointCoordinate(0.62, 0.12),
                                      PointCoordinate(0.61, 0.22),
                                      PointCoordinate(0.49, 0.21),
                                      PointCoordinate(0.50, 0.10),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.53, 0.13),
                                      PointCoordinate(0.53, 0.18),
                                      PointCoordinate(0.58, 0.18),
                                      PointCoordinate(0.58, 0.13),
                                      PointCoordinate(0.53, 0.13),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.545, 0.145),
                                      PointCoordinate(0.560, 0.150),
                                      PointCoordinate(0.555, 0.165),
                                      PointCoordinate(0.540, 0.160),
                                      PointCoordinate(0.545, 0.145),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                       "blueberry_quality": 2
                  },
              ],
              105: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fourth donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.33, 0.33),
                                      PointCoordinate(0.47, 0.34),
                                      PointCoordinate(0.45, 0.46),
                                      PointCoordinate(0.31, 0.45),
                                      PointCoordinate(0.33, 0.33),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.36, 0.36),
                                      PointCoordinate(0.37, 0.41),
                                      PointCoordinate(0.42, 0.42),
                                      PointCoordinate(0.43, 0.37),
                                      PointCoordinate(0.36, 0.36),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.375, 0.375),
                                      PointCoordinate(0.395, 0.380),
                                      PointCoordinate(0.390, 0.395),
                                      PointCoordinate(0.370, 0.390),
                                      PointCoordinate(0.375, 0.375),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                       "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Second donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.33, 0.12),
                                      PointCoordinate(0.46, 0.13),
                                      PointCoordinate(0.44, 0.26),
                                      PointCoordinate(0.31, 0.25),
                                      PointCoordinate(0.33, 0.12),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.36, 0.16),
                                      PointCoordinate(0.37, 0.21),
                                      PointCoordinate(0.41, 0.22),
                                      PointCoordinate(0.42, 0.17),
                                      PointCoordinate(0.36, 0.16),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.375, 0.175),
                                      PointCoordinate(0.390, 0.180),
                                      PointCoordinate(0.385, 0.195),
                                      PointCoordinate(0.370, 0.190),
                                      PointCoordinate(0.375, 0.175),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                       "blueberry_quality": 8
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          polygons=[
                              # Fifth donut + inner polygon
                              [
                                  # Outer ring
                                  [
                                      PointCoordinate(0.53, 0.13),
                                      PointCoordinate(0.67, 0.14),
                                      PointCoordinate(0.66, 0.26),
                                      PointCoordinate(0.52, 0.25),
                                      PointCoordinate(0.53, 0.13),
                                  ],
                                  # Inner ring
                                  [
                                      PointCoordinate(0.56, 0.16),
                                      PointCoordinate(0.57, 0.21),
                                      PointCoordinate(0.62, 0.22),
                                      PointCoordinate(0.63, 0.17),
                                      PointCoordinate(0.56, 0.16),
                                  ],
                              ],
                              # Shape inside the hole
                              [
                                  [
                                      PointCoordinate(0.575, 0.175),
                                      PointCoordinate(0.595, 0.180),
                                      PointCoordinate(0.590, 0.195),
                                      PointCoordinate(0.570, 0.190),
                                      PointCoordinate(0.575, 0.175),
                                  ]
                              ],
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                       "blueberry_quality": 6
                  },
              ],
          },
      }

      # Loop through each data unit (image, video, etc.)
      for data_unit, frame_coordinates in video_frame_labels.items():
          object_instances_by_label_ref = {}

          # Get the label row for the current data unit
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"
          assert label_rows, f"No label rows found for data unit: {data_unit}"

          label_row = label_rows[0]
          assert label_row is not None, f"Label row is None for {data_unit}"

          # Initialize label row using bundle
          with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
              label_row.initialise_labels()
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              for frame_number, items in frame_coordinates.items():
                  assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"

                  if not isinstance(items, list):  # Single or multiple objects in the frame
                      items = [items]

                  for item in items:
                      label_ref = item["label_ref"]
                      coord = item["coordinates"]
                      blueberry_type = item["blueberry_type"]
                      blueberry_quality = item["blueberry_quality"]

                      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(", ")

                          for quality in quality_options:
                              option = None
                              if quality == "Plump":
                                  option = (
                                      bluegold_plump_option
                                      if blueberry_type == "Bluegold"
                                      else duke_plump_option
                                      if blueberry_type == "Duke"
                                      else blueray_plump_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Juicy":
                                  option = (
                                      bluegold_juicy_option
                                      if blueberry_type == "Bluegold"
                                      else duke_juicy_option
                                      if blueberry_type == "Duke"
                                      else blueray_juicy_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Large":
                                  option = (
                                      bluegold_large_option
                                      if blueberry_type == "Bluegold"
                                      else duke_large_option
                                      if blueberry_type == "Duke"
                                      else blueray_large_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )

                              if option:
                                  checklist_answers.append(option)
                              else:
                                  assert blueberry_type == "Other blueberry type", (
                                      f"Invalid quality '{quality}' for type '{blueberry_type}'"
                                  )

                          if checklist_attribute and checklist_answers:
                              polygon_object_instance.set_answer(
                                  attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                              )

                      else:
                          polygon_object_instance = object_instances_by_label_ref[label_ref]

                      # Assign the object to the frame and track it
                      polygon_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

              # Add object instances to label_row **only if they have frames assigned**
              for polygon_object_instance in object_instances_by_label_ref.values():
                  assert isinstance(polygon_object_instance, ObjectInstance), "Expected ObjectInstance type"
                  if polygon_object_instance.get_annotation_frames():
                      label_row.add_object_instance(polygon_object_instance)

              # Save label row using the bundle
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)

      print("Labels with blueberry type radio buttons, checklist attributes, number attributes, and text labels added for all data units.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DEPRECATED - Polygons">
    While this method works for simple polygons, we STRONGLY recommend using the new Polygon method for creating simple polygons.

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling
    * Radio button options
    * Checklist options
    * Text input
    * Number input

    <CodeGroup>
      ```python DEPRECATED - Polygons expandable theme={"dark"}

      # Import dependencies
      from pathlib import Path

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

      # 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"
      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"

      # Find polygon object for blueberries
      polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="Blueberries", type_=Object)
      assert polygon_ontology_object is not None, "Object 'Blueberries' not found in ontology"

      # Get radio attribute for blueberry type
      blueberry_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert blueberry_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

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

      # Get radio options
      bluegold_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Bluegold")
      assert bluegold_option is not None, "Option 'Bluegold' not found under radio attribute 'Type?'"

      duke_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Duke")
      assert duke_option is not None, "Option 'Duke' not found under radio attribute 'Type?'"

      blueray_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Blueray")
      assert blueray_option is not None, "Option 'Blueray' not found under radio attribute 'Type?'"

      other_blueberry_option = blueberry_type_radio_attribute.get_child_by_title(type_=Option, title="Other blueberry type")
      assert other_blueberry_option is not None, "Option 'Other blueberry type' not found under radio attribute 'Type?'"

      # Bluegold Qualities
      bluegold_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Bluegold Qualities?"
      )
      assert bluegold_checklist_attribute is not None, "Checklist attribute 'Bluegold Qualities?' not found"

      bluegold_plump_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert bluegold_plump_option is not None, "Option 'Plump' not found under 'Bluegold Qualities?'"

      bluegold_juicy_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert bluegold_juicy_option is not None, "Option 'Juicy' not found under 'Bluegold Qualities?'"

      bluegold_large_option = bluegold_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert bluegold_large_option is not None, "Option 'Large' not found under 'Bluegold Qualities?'"

      # Duke Qualities
      duke_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Duke Qualities?")
      assert duke_checklist_attribute is not None, "Checklist attribute 'Duke Qualities?' not found"

      duke_plump_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert duke_plump_option is not None, "Option 'Plump' not found under 'Duke Qualities?'"

      duke_juicy_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert duke_juicy_option is not None, "Option 'Juicy' not found under 'Duke Qualities?'"

      duke_large_option = duke_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert duke_large_option is not None, "Option 'Large' not found under 'Duke Qualities?'"

      # Blueray Qualities
      blueray_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Blueray Qualities?"
      )
      assert blueray_checklist_attribute is not None, "Checklist attribute 'Blueray Qualities?' not found"

      blueray_plump_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert blueray_plump_option is not None, "Option 'Plump' not found under 'Blueray Qualities?'"

      blueray_juicy_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert blueray_juicy_option is not None, "Option 'Juicy' not found under 'Blueray Qualities?'"

      blueray_large_option = blueray_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert blueray_large_option is not None, "Option 'Large' not found under 'Blueray Qualities?'"

      # Other blueberry type — text input
      other_blueberry_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify blueberry type"
      )
      assert other_blueberry_option_text_attribute is not None, "Text attribute 'Specify blueberry type' not found"

      # Dictionary of labels per data unit and per frame with blueberry type specified, including quality options
      video_frame_labels = {
          "blueberries-001.jpg": {
              0: {
                  "label_ref": "blueberry_001",
                  "coordinates": PolygonCoordinates(
                      [
                          PointCoordinate(0.01, 0.02),
                          PointCoordinate(0.03, 0.03),
                          PointCoordinate(0.05, 0.02),
                          PointCoordinate(0.04, 0.01),
                          PointCoordinate(0.02, 0.01),
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                  "blueberry_quality": 7
              }
          },
          "blueberries-010.jpg": {
              0: [
                  {
                      "label_ref": "blueberry_002",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.01, 0.02),
                              PointCoordinate(0.03, 0.03),
                              PointCoordinate(0.05, 0.02),
                              PointCoordinate(0.04, 0.01),
                              PointCoordinate(0.02, 0.01),
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_003",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.04, 0.05),
                              PointCoordinate(0.06, 0.06),
                              PointCoordinate(0.08, 0.05),
                              PointCoordinate(0.07, 0.04),
                              PointCoordinate(0.05, 0.04),
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                  },
                  {
                      "label_ref": "blueberry_004",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.07, 0.02),
                              PointCoordinate(0.09, 0.03),
                              PointCoordinate(0.11, 0.02),
                              PointCoordinate(0.10, 0.01),
                              PointCoordinate(0.08, 0.01),
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                  },
              ],
          },
          "blueberries-ig": {
              0: {
                  "label_ref": "blueberry_005",
                  "coordinates": PolygonCoordinates(
                      [
                          PointCoordinate(0.01, 0.02),
                          PointCoordinate(0.03, 0.03),
                          PointCoordinate(0.05, 0.02),
                          PointCoordinate(0.04, 0.01),
                          PointCoordinate(0.02, 0.01),
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump, Juicy",
                  "blueberry_quality": 8
              },
              2: [
                  {
                      "label_ref": "blueberry_006",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.01, 0.02),
                              PointCoordinate(0.03, 0.03),
                              PointCoordinate(0.05, 0.02),
                              PointCoordinate(0.04, 0.01),
                              PointCoordinate(0.02, 0.01),
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Large",
                      "blueberry_quality": 7
                  },
                  {
                      "label_ref": "blueberry_007",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.04, 0.05),
                              PointCoordinate(0.06, 0.06),
                              PointCoordinate(0.08, 0.05),
                              PointCoordinate(0.07, 0.04),
                              PointCoordinate(0.05, 0.04),
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 4
                  },
                  {
                      "label_ref": "blueberry_008",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.07, 0.02),
                              PointCoordinate(0.09, 0.03),
                              PointCoordinate(0.11, 0.02),
                              PointCoordinate(0.10, 0.01),
                              PointCoordinate(0.08, 0.01),
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 3
                  },
              ],
          },
          "blueberries-is": {
              0: {
                  "label_ref": "blueberry_009",
                  "coordinates": PolygonCoordinates(
                      [
                          PointCoordinate(0.01, 0.02),
                          PointCoordinate(0.03, 0.03),
                          PointCoordinate(0.05, 0.02),
                          PointCoordinate(0.04, 0.01),
                          PointCoordinate(0.02, 0.01),
                      ]
                  ),
                  "blueberry_type": "Bluegold",
                  "bluegold_quality_options": "Plump",
                  "blueberry_quality": 5
              },
              3: [
                  {
                      "label_ref": "blueberry_010",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.01, 0.02),
                              PointCoordinate(0.03, 0.03),
                              PointCoordinate(0.05, 0.02),
                              PointCoordinate(0.04, 0.01),
                              PointCoordinate(0.02, 0.01),
                          ]
                      ),
                      "blueberry_type": "Duke",
                      "duke_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_011",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.04, 0.05),
                              PointCoordinate(0.06, 0.06),
                              PointCoordinate(0.08, 0.05),
                              PointCoordinate(0.07, 0.04),
                              PointCoordinate(0.05, 0.04),
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 5
                  },
                  {
                      "label_ref": "blueberry_012",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.07, 0.02),
                              PointCoordinate(0.09, 0.03),
                              PointCoordinate(0.11, 0.02),
                              PointCoordinate(0.10, 0.01),
                              PointCoordinate(0.08, 0.01),
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Powder Blue",
                      "blueberry_quality": 4
                  },
              ],
          },
          "blueberries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "blueberry_013",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.01, 0.02),
                              PointCoordinate(0.03, 0.03),
                              PointCoordinate(0.05, 0.02),
                              PointCoordinate(0.04, 0.01),
                              PointCoordinate(0.02, 0.01),
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 4
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.04, 0.05),
                              PointCoordinate(0.06, 0.06),
                              PointCoordinate(0.08, 0.05),
                              PointCoordinate(0.07, 0.04),
                              PointCoordinate(0.05, 0.04),
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_015",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.07, 0.02),
                              PointCoordinate(0.09, 0.03),
                              PointCoordinate(0.11, 0.02),
                              PointCoordinate(0.10, 0.01),
                              PointCoordinate(0.08, 0.01),
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Lowbush",
                      "blueberry_quality": 6
                  },
              ],
              104: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.01, 0.02),
                              PointCoordinate(0.03, 0.03),
                              PointCoordinate(0.05, 0.02),
                              PointCoordinate(0.04, 0.01),
                              PointCoordinate(0.02, 0.01),
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.041, 0.052),
                              PointCoordinate(0.061, 0.062),
                              PointCoordinate(0.081, 0.052),
                              PointCoordinate(0.071, 0.042),
                              PointCoordinate(0.051, 0.042),
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 9
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.07, 0.02),
                              PointCoordinate(0.09, 0.03),
                              PointCoordinate(0.11, 0.02),
                              PointCoordinate(0.10, 0.01),
                              PointCoordinate(0.08, 0.01),
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Highbush",
                      "blueberry_quality": 6
                  },
              ],
              105: [
                  {
                      "label_ref": "blueberry_016",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.011, 0.022),
                              PointCoordinate(0.031, 0.032),
                              PointCoordinate(0.051, 0.022),
                              PointCoordinate(0.041, 0.012),
                              PointCoordinate(0.021, 0.012),
                          ]
                      ),
                      "blueberry_type": "Blueray",
                      "blueray_quality_options": "Plump",
                      "blueberry_quality": 6
                  },
                  {
                      "label_ref": "blueberry_014",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.043, 0.055),
                              PointCoordinate(0.063, 0.065),
                              PointCoordinate(0.083, 0.055),
                              PointCoordinate(0.073, 0.045),
                              PointCoordinate(0.053, 0.045),
                          ]
                      ),
                      "blueberry_type": "Bluegold",
                      "bluegold_quality_options": "Plump, Juicy, Large",
                      "blueberry_quality": 7
                  },
                  {
                      "label_ref": "blueberry_017",
                      "coordinates": PolygonCoordinates(
                          [
                              PointCoordinate(0.071, 0.022),
                              PointCoordinate(0.091, 0.032),
                              PointCoordinate(0.111, 0.022),
                              PointCoordinate(0.101, 0.012),
                              PointCoordinate(0.081, 0.012),
                          ]
                      ),
                      "blueberry_type": "Other blueberry type",
                      "Specify blueberry type": "Powder Blue",
                      "blueberry_quality": 1
                  },
              ],
          },
      }


      # Loop through each data unit (image, video, etc.)
      for data_unit, frame_coordinates in video_frame_labels.items():
          object_instances_by_label_ref = {}

          # Get the label row for the current data unit
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"
          assert label_rows, f"No label rows found for data unit: {data_unit}"

          label_row = label_rows[0]
          assert label_row is not None, f"Label row is None for {data_unit}"

          # Initialize label row using bundle
          with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
              label_row.initialise_labels()
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              for frame_number, items in frame_coordinates.items():
                  assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"

                  if not isinstance(items, list):  # Single or multiple objects in the frame
                      items = [items]

                  for item in items:
                      label_ref = item["label_ref"]
                      coord = item["coordinates"]
                      blueberry_type = item["blueberry_type"]
                      blueberry_quality = item["blueberry_quality"]

                      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(", ")

                          for quality in quality_options:
                              option = None
                              if quality == "Plump":
                                  option = (
                                      bluegold_plump_option
                                      if blueberry_type == "Bluegold"
                                      else duke_plump_option
                                      if blueberry_type == "Duke"
                                      else blueray_plump_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Juicy":
                                  option = (
                                      bluegold_juicy_option
                                      if blueberry_type == "Bluegold"
                                      else duke_juicy_option
                                      if blueberry_type == "Duke"
                                      else blueray_juicy_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )
                              elif quality == "Large":
                                  option = (
                                      bluegold_large_option
                                      if blueberry_type == "Bluegold"
                                      else duke_large_option
                                      if blueberry_type == "Duke"
                                      else blueray_large_option
                                      if blueberry_type == "Blueray"
                                      else None
                                  )

                              if option:
                                  checklist_answers.append(option)
                              else:
                                  assert blueberry_type == "Other blueberry type", (
                                      f"Invalid quality '{quality}' for type '{blueberry_type}'"
                                  )

                          if checklist_attribute and checklist_answers:
                              polygon_object_instance.set_answer(
                                  attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                              )

                      else:
                          polygon_object_instance = object_instances_by_label_ref[label_ref]

                      # Assign the object to the frame and track it
                      polygon_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

              # Add object instances to label_row **only if they have frames assigned**
              for polygon_object_instance in object_instances_by_label_ref.values():
                  assert isinstance(polygon_object_instance, ObjectInstance), "Expected ObjectInstance type"
                  if polygon_object_instance.get_annotation_frames():
                      label_row.add_object_instance(polygon_object_instance)

              # Save label row using the bundle
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)

      print("Labels with blueberry type radio buttons, checklist attributes, number attributes, and text labels added for all data units.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Polyline">
    **Basic**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling

    **Advanced**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling
    * Radio button options
    * Checklist options
    * Text input
    * Number input

    **Polyline Ontology**

    ![Polyline Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/labels-polylines-branches.png)

    <CodeGroup>
      ```python Polylines Images/Videos - Basic expandable theme={"dark"}

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

      # 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 Project ID
      BUNDLE_SIZE = 10

      # Data unit titles in your Project
      IMAGE_TITLE = "cherries-001.jpg"
      IMG_GROUP_TITLE = "cherries-ig"
      IMG_SEQUENCE_TITLE = "cherries-is"
      VIDEO_TITLE = "cherries-vid-001.mp4"

      # Ontology object title for your POLYLINE object
      POLYLINE_OBJECT_TITLE = "Branches"

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Find a POLYLINE object in the ontology by title
      ontology_structure = project.ontology_structure
      polyline_object: Object = ontology_structure.get_child_by_title(title=POLYLINE_OBJECT_TITLE, type_=Object)
      assert polyline_object is not None, f"Polyline object '{POLYLINE_OBJECT_TITLE}' not found in ontology."

      # Initialise label rows
      label_rows = {}
      all_titles = [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in all_titles:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Polyline coordinates: A simple bent line with 5 vertices
      pline = PolylineCoordinates([
          PointCoordinate(0.10, 0.80),
          PointCoordinate(0.20, 0.60),
          PointCoordinate(0.40, 0.55),
          PointCoordinate(0.65, 0.40),
          PointCoordinate(0.85, 0.35),
      ])

      # Create instances and attach to frames
      label_rows_to_save = []

      # 1. One image > frame 0
      image_lr = label_rows.get(IMAGE_TITLE)
      if image_lr is not None:
          inst: ObjectInstance = polyline_object.create_instance()
          inst.set_for_frames(coordinates=pline, frames=0)
          image_lr.add_object_instance(inst)
          label_rows_to_save.append(image_lr)

      # 2. One image group > frame 0
      img_group_lr = label_rows.get(IMG_GROUP_TITLE)
      if img_group_lr is not None:
          inst: ObjectInstance = polyline_object.create_instance()
          inst.set_for_frames(coordinates=pline, frames=0)
          img_group_lr.add_object_instance(inst)
          label_rows_to_save.append(img_group_lr)

      # 3. One image sequence > frame 0
      img_sequence_lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if img_sequence_lr is not None:
          inst: ObjectInstance = polyline_object.create_instance()
          inst.set_for_frames(coordinates=pline, frames=0)
          img_sequence_lr.add_object_instance(inst)
          label_rows_to_save.append(img_sequence_lr)

      # 4. One video > reuse SAME instance across 3 consecutive frames (frames 100, 101, 102)
      video_lr = label_rows.get(VIDEO_TITLE)
      if video_lr is not None:
          inst: ObjectInstance = polyline_object.create_instance()
          for f in [100, 101, 102]:
              inst.set_for_frames(coordinates=pline, frames=f)
          video_lr.add_object_instance(inst)
          label_rows_to_save.append(video_lr)

      # Save label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in label_rows_to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: created one polyline on image, image group, image sequence, and 3 video frames.")

      ```

      ```python Polylines Images/Videos - Advanced expandable theme={"dark"}

      # 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, PolylineCoordinates
      from encord.objects.attributes import NumericAttribute

      # 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"
      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"

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

      # Get radio attribute for branch type
      branch_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert branch_type_radio_attribute is not None, "Radio attribute 'Type?' not found in ontology"

      # Get radio options
      fruiting_spur_option = branch_type_radio_attribute.get_child_by_title(type_=Option, title="Fruiting spur")
      assert fruiting_spur_option is not None, "Option 'Fruiting spur' not found under radio attribute 'Type?'"

      sucker_option = branch_type_radio_attribute.get_child_by_title(type_=Option, title="Sucker")
      assert sucker_option is not None, "Option 'Sucker' not found under radio attribute 'Type?'"

      side_shoot_option = branch_type_radio_attribute.get_child_by_title(type_=Option, title="Side shoot")
      assert side_shoot_option is not None, "Option 'Side shoot' not found under radio attribute 'Type?'"

      other_branch_option = branch_type_radio_attribute.get_child_by_title(type_=Option, title="Other branch type")
      assert other_branch_option is not None, "Option 'Other branch type' not found under radio attribute 'Type?'"

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

      # Fruiting spur Qualities
      fruiting_spur_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Fruiting spur Qualities?"
      )
      assert fruiting_spur_checklist_attribute is not None, "Checklist attribute 'Fruiting spur Qualities?' not found"

      fruiting_spur_short_length_option = fruiting_spur_checklist_attribute.get_child_by_title(
          type_=Option, title="Short length"
      )
      assert fruiting_spur_short_length_option is not None, "Option 'Short length' not found under 'Fruiting spur Qualities?'"

      fruiting_spur_high_bud_density_option = fruiting_spur_checklist_attribute.get_child_by_title(
          type_=Option, title="High bud density"
      )
      assert fruiting_spur_high_bud_density_option is not None, (
          "Option 'High bud density' not found under 'Fruiting spur Qualities?'"
      )

      fruiting_spur_healthy_option = fruiting_spur_checklist_attribute.get_child_by_title(type_=Option, title="Healthy")
      assert fruiting_spur_healthy_option is not None, "Option 'Healthy' not found under 'Fruiting spur Qualities?'"

      # Sucker Qualities
      sucker_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Sucker Qualities?")
      assert sucker_checklist_attribute is not None, "Checklist attribute 'Sucker Qualities?' not found"

      sucker_short_length_option = sucker_checklist_attribute.get_child_by_title(type_=Option, title="Short length")
      assert sucker_short_length_option is not None, "Option 'Short length' not found under 'Sucker Qualities?'"

      sucker_high_bud_density_option = sucker_checklist_attribute.get_child_by_title(type_=Option, title="High bud density")
      assert sucker_high_bud_density_option is not None, "Option 'High bud density' not found under 'Sucker Qualities?'"

      sucker_healthy_option = sucker_checklist_attribute.get_child_by_title(type_=Option, title="Healthy")
      assert sucker_healthy_option is not None, "Option 'Healthy' not found under 'Sucker Qualities?'"

      # Side shoot Qualities
      side_shoot_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Side shoot Qualities?"
      )
      assert side_shoot_checklist_attribute is not None, "Checklist attribute 'Side shoot Qualities?' not found"

      side_shoot_short_length_option = side_shoot_checklist_attribute.get_child_by_title(type_=Option, title="Short length")
      assert side_shoot_short_length_option is not None, "Option 'Short length' not found under 'Side shoot Qualities?'"

      side_shoot_high_bud_density_option = side_shoot_checklist_attribute.get_child_by_title(
          type_=Option, title="High bud density"
      )
      assert side_shoot_high_bud_density_option is not None, (
          "Option 'High bud density' not found under 'Side shoot Qualities?'"
      )

      side_shoot_healthy_option = side_shoot_checklist_attribute.get_child_by_title(type_=Option, title="Healthy")
      assert side_shoot_healthy_option is not None, "Option 'Healthy' not found under 'Side shoot Qualities?'"

      # Other branch type text attribute
      other_branch_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify branch type"
      )
      assert other_branch_option_text_attribute is not None, "Text attribute 'Specify branch type' not found"


      # Dictionary of labels per data unit and per frame with branch type specified, including quality options
      video_image_frame_labels = {
          "cherries-001.jpg": {
              0: {
                  "label_ref": "branch_001",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate(0.013, 0.023),
                          PointCoordinate(0.033, 0.033),
                          PointCoordinate(0.053, 0.023),
                          PointCoordinate(0.043, 0.013),
                      ]
                  ),
                  "branch_type": "Fruiting spur",
                  "fruiting_spur_quality_options": "Short length, High bud density",
                  "quality_number": 8
              }
          },
          "cherries-010.jpg": {
              0: [
                  {
                      "label_ref": "branch_002",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.03, 0.023),
                              PointCoordinate(0.033, 0.033),
                              PointCoordinate(0.053, 0.033),
                              PointCoordinate(0.043, 0.013),
                          ]
                      ),
                      "branch_type": "Sucker",
                      "sucker_quality_options": "Short length, High bud density, Healthy",
                      "quality_number": 7
                  },
                  {
                      "label_ref": "branch_003",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.043, 0.053),
                              PointCoordinate(0.063, 0.063),
                              PointCoordinate(0.083, 0.053),
                              PointCoordinate(0.073, 0.043),
                          ]
                      ),
                      "branch_type": "Side shoot",
                      "side_shoot_quality_options": "Short length",
                      "quality_number": 8
                  },
                  {
                      "label_ref": "branch_004",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.073, 0.023),
                              PointCoordinate(0.093, 0.033),
                              PointCoordinate(0.113, 0.023),
                              PointCoordinate(0.103, 0.013),
                          ]
                      ),
                      "branch_type": "Other branch type",
                      "Specify branch type": "Cane",
                      "quality_number": 5
                  },
              ],
          },
          "cherries-ig": {
              0: {
                  "label_ref": "branch_005",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate(0.013, 0.023),
                          PointCoordinate(0.033, 0.033),
                          PointCoordinate(0.053, 0.023),
                          PointCoordinate(0.043, 0.013),
                      ]
                  ),
                  "branch_type": "Fruiting spur",
                  "fruiting_spur_quality_options": "Short length, High bud density",
                  "quality_number": 9
              },
              2: [
                  {
                      "label_ref": "branch_006",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.013, 0.023),
                              PointCoordinate(0.033, 0.033),
                              PointCoordinate(0.053, 0.023),
                              PointCoordinate(0.043, 0.013),
                          ]
                      ),
                      "branch_type": "Sucker",
                      "sucker_quality_options": "Healthy",
                      "quality_number": 6
                  },
                  {
                      "label_ref": "branch_007",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.043, 0.053),
                              PointCoordinate(0.063, 0.063),
                              PointCoordinate(0.083, 0.053),
                              PointCoordinate(0.073, 0.043),
                          ]
                      ),
                      "branch_type": "Side shoot",
                      "side_shoot_quality_options": "Short length",
                      "quality_number": 5
                  },
                  {
                      "label_ref": "branch_008",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.073, 0.023),
                              PointCoordinate(0.093, 0.033),
                              PointCoordinate(0.113, 0.023),
                              PointCoordinate(0.103, 0.013),
                          ]
                      ),
                      "branch_type": "Other branch type",
                      "Specify branch type": "Cane",
                      "quality_number": 4
                  },
              ],
          },
          "cherries-is": {
              0: {
                  "label_ref": "branch_009",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate(0.013, 0.023),
                          PointCoordinate(0.033, 0.033),
                          PointCoordinate(0.053, 0.023),
                          PointCoordinate(0.043, 0.013),
                      ]
                  ),
                  "branch_type": "Fruiting spur",
                  "fruiting_spur_quality_options": "Short length",
                  "quality_number": 7
              },
              3: [
                  {
                      "label_ref": "branch_010",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.013, 0.023),
                              PointCoordinate(0.033, 0.033),
                              PointCoordinate(0.053, 0.023),
                              PointCoordinate(0.043, 0.013),
                          ]
                      ),
                      "branch_type": "Sucker",
                      "sucker_quality_options": "Short length, High bud density, Healthy",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "branch_011",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.043, 0.053),
                              PointCoordinate(0.063, 0.063),
                              PointCoordinate(0.083, 0.053),
                              PointCoordinate(0.073, 0.043),
                          ]
                      ),
                      "branch_type": "Side shoot",
                      "side_shoot_quality_options": "Short length",
                      "quality_number": 6
                  },
                  {
                      "label_ref": "branch_012",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.073, 0.023),
                              PointCoordinate(0.093, 0.033),
                              PointCoordinate(0.113, 0.023),
                              PointCoordinate(0.103, 0.013),
                          ]
                      ),
                      "branch_type": "Other branch type",
                      "Specify branch type": "Cane",
                      "quality_number": 7
                  },
              ],
          },
          "cherries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "branch_013",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.013, 0.023),
                              PointCoordinate(0.033, 0.033),
                              PointCoordinate(0.053, 0.023),
                              PointCoordinate(0.043, 0.013),
                          ]
                      ),
                      "branch_type": "Side shoot",
                      "side_shoot_quality_options": "Short length",
                      "quality_number": 8
                  },
                  {
                      "label_ref": "branch_014",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.043, 0.053),
                              PointCoordinate(0.063, 0.063),
                              PointCoordinate(0.083, 0.053),
                              PointCoordinate(0.073, 0.043),
                          ]
                      ),
                      "branch_type": "Fruiting spur",
                      "fruiting_spur_quality_options": "Short length, High bud density, Healthy",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "branch_015",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.073, 0.023),
                              PointCoordinate(0.093, 0.033),
                              PointCoordinate(0.113, 0.023),
                              PointCoordinate(0.103, 0.013),
                          ]
                      ),
                      "branch_type": "Other branch type",
                      "Specify branch type": "Cane",
                      "quality_number": 5
                  },
              ],
              104: [
                  {
                      "label_ref": "branch_016",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.013, 0.023),
                              PointCoordinate(0.033, 0.033),
                              PointCoordinate(0.053, 0.023),
                              PointCoordinate(0.043, 0.013),
                          ]
                      ),
                      "branch_type": "Side shoot",
                      "side_shoot_quality_options": "Short length",
                      "quality_number": 8
                  },
                  {
                      "label_ref": "branch_014",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.0413, 0.0523),
                              PointCoordinate(0.0613, 0.0623),
                              PointCoordinate(0.0813, 0.0523),
                              PointCoordinate(0.0713, 0.0423),
                          ]
                      ),
                      "branch_type": "Fruiting spur",
                      "fruiting_spur_quality_options": "Short length, High bud density, Healthy",
                      "quality_number": 7
                  },
                  {
                      "label_ref": "branch_017",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.073, 0.023),
                              PointCoordinate(0.093, 0.033),
                              PointCoordinate(0.113, 0.023),
                              PointCoordinate(0.103, 0.013),
                          ]
                      ),
                      "branch_type": "Other branch type",
                      "Specify branch type": "Cane",
                      "quality_number": 4
                  },
              ],
              105: [
                  {
                      "label_ref": "branch_016",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.0113, 0.0223),
                              PointCoordinate(0.0313, 0.0323),
                              PointCoordinate(0.0513, 0.0223),
                              PointCoordinate(0.0413, 0.0123),
                          ]
                      ),
                      "branch_type": "Side shoot",
                      "side_shoot_quality_options": "Short length",
                      "quality_number": 3
                  },
                  {
                      "label_ref": "branch_014",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.0433, 0.0553),
                              PointCoordinate(0.0633, 0.0653),
                              PointCoordinate(0.0833, 0.0553),
                              PointCoordinate(0.0733, 0.0453),
                          ]
                      ),
                      "branch_type": "Fruiting spur",
                      "fruiting_spur_quality_options": "Short length, High bud density, Healthy",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "branch_017",
                      "coordinates": PolylineCoordinates(
                          [
                              PointCoordinate(0.0713, 0.0223),
                              PointCoordinate(0.0913, 0.0323),
                              PointCoordinate(0.1113, 0.0223),
                              PointCoordinate(0.1013, 0.0123),
                          ]
                      ),
                      "branch_type": "Other branch type",
                      "Specify branch type": "Cane",
                      "quality_number": 2
                  },
              ],
          },
      }

      # Cache label rows after initialization
      label_row_map = {}

      # Step 1: Initialize all label rows using a bundle
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for data_unit in video_image_frame_labels.keys():
              label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
              assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"

              if not label_rows:
                  print(f"Skipping: No label row found for {data_unit}")
                  continue

              label_row = label_rows[0]
              label_row.initialise_labels(bundle=bundle)
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              label_row_map[data_unit] = label_row  # Cache the initialized label row

      # Step 2: Process all frame coordinates and prepare label rows for saving
      label_rows_to_save = []

      for data_unit, frame_coordinates in video_image_frame_labels.items():
          label_row = label_row_map.get(data_unit)
          assert label_row is not None, f"Label row not initialized for {data_unit}"

          object_instances_by_label_ref = {}

          for frame_number, items in frame_coordinates.items():
              assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"
              if not isinstance(items, list):
                  items = [items]

              for item in items:
                  label_ref = item["label_ref"]
                  coord = item["coordinates"]
                  branch_type = item["branch_type"]
                  quality_number = item["quality_number"]


                  assert branch_type in {
                      "Fruiting spur",
                      "Sucker",
                      "Side shoot",
                      "Other branch type",
                  }, f"Unexpected branch type '{branch_type}' in {data_unit}"

                  if label_ref not in object_instances_by_label_ref:
                      polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()
                      assert polyline_object_instance is not None, "Failed to create ObjectInstance"
                      checklist_attribute = None
                      quality_options = []

                      # Set quality number attribute 
                      polyline_object_instance.set_answer(attribute=quality_number_attribute, answer=quality_number)

                      # Assign radio and checklist attributes based on branch type
                      if branch_type == "Fruiting spur":
                          assert fruiting_spur_option is not None, "Missing 'fruiting_spur_option'"
                          polyline_object_instance.set_answer(
                              attribute=branch_type_radio_attribute, answer=fruiting_spur_option
                          )
                          checklist_attribute = fruiting_spur_checklist_attribute
                          quality_options = item.get("fruiting_spur_quality_options", "").split(", ")
                      elif branch_type == "Sucker":
                          assert sucker_option is not None, "Missing 'sucker_option'"
                          polyline_object_instance.set_answer(attribute=branch_type_radio_attribute, answer=sucker_option)
                          checklist_attribute = sucker_checklist_attribute
                          quality_options = item.get("sucker_quality_options", "").split(", ")
                      elif branch_type == "Side shoot":
                          assert side_shoot_option is not None, "Missing 'side_shoot_option'"
                          polyline_object_instance.set_answer(attribute=branch_type_radio_attribute, answer=side_shoot_option)
                          checklist_attribute = side_shoot_checklist_attribute
                          quality_options = item.get("side_shoot_quality_options", "").split(", ")
                      elif branch_type == "Other branch type":
                          assert other_branch_option is not None, "Missing 'other_branch_option'"
                          polyline_object_instance.set_answer(
                              attribute=branch_type_radio_attribute, answer=other_branch_option
                          )
                          text_answer = item.get("Specify branch type", "")
                          assert isinstance(text_answer, str), "'Specify branch type' must be a string"
                          polyline_object_instance.set_answer(
                              attribute=other_branch_option_text_attribute, answer=text_answer
                          )
                          quality_options = []

                      # Process checklist options
                      checklist_answers = []
                      for quality in quality_options:
                          option = None
                          if quality == "Short length":
                              option = (
                                  fruiting_spur_short_length_option
                                  if branch_type == "Fruiting spur"
                                  else sucker_short_length_option
                                  if branch_type == "Sucker"
                                  else side_shoot_short_length_option
                                  if branch_type == "Side shoot"
                                  else None
                              )
                          elif quality == "High bud density":
                              option = (
                                  fruiting_spur_high_bud_density_option
                                  if branch_type == "Fruiting spur"
                                  else sucker_high_bud_density_option
                                  if branch_type == "Sucker"
                                  else side_shoot_high_bud_density_option
                                  if branch_type == "Side shoot"
                                  else None
                              )
                          elif quality == "Healthy":
                              option = (
                                  fruiting_spur_healthy_option
                                  if branch_type == "Fruiting spur"
                                  else sucker_healthy_option
                                  if branch_type == "Sucker"
                                  else side_shoot_healthy_option
                                  if branch_type == "Side shoot"
                                  else None
                              )

                          if option:
                              checklist_answers.append(option)
                          else:
                              assert branch_type == "Other branch type", (
                                  f"Invalid quality '{quality}' for branch type '{branch_type}'"
                              )

                      if checklist_attribute and checklist_answers:
                          polyline_object_instance.set_answer(
                              attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                          )

                      object_instances_by_label_ref[label_ref] = polyline_object_instance

                  else:
                      polyline_object_instance = object_instances_by_label_ref[label_ref]

                  # Assign coordinates for this frame
                  polyline_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

          # Add object instances to the label row if they have frames assigned
          for polyline_object_instance in object_instances_by_label_ref.values():
              assert isinstance(polyline_object_instance, ObjectInstance), "Expected ObjectInstance type"
              if polyline_object_instance.get_annotation_frames():
                  label_row.add_object_instance(polyline_object_instance)

          label_rows_to_save.append(label_row)

      # Step 3: Save all label rows using a bundle
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for label_row in label_rows_to_save:
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)
              print(f"Saved label row for {label_row.data_title}")

      print("Labels with branch type radio buttons, checklist attributes, number attributes, and text labels added for all data units.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Keypoint">
    **Basic**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling

    **Advanced**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling
    * Radio button options
    * Checklist options
    * Text input
    * Number input

    **Keypoint Ontology**

    ![Keypoint Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/labels-keypoints-floral-axis.png)

    <CodeGroup>
      ```python Keypoints Images/Videos expandable theme={"dark"}

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

      # 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 Project ID
      BUNDLE_SIZE = 10

      # Data unit titles in your Project
      IMAGE_TITLE = "blueberries-001.jpg"
      IMG_GROUP_TITLE = "blueberries-ig"
      IMG_SEQUENCE_TITLE = "blueberries-is"
      VIDEO_TITLE = "blueberries-vid-001.mp4"

      # Ontology object title for your KEYPOINT object
      KEYPOINT_OBJECT_TITLE = "Floral axis"

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Find a KEYPOINT object in the ontology by title
      ontology_structure = project.ontology_structure
      keypoint_object: Object = ontology_structure.get_child_by_title(title=KEYPOINT_OBJECT_TITLE, type_=Object)
      assert keypoint_object is not None, f"Keypoint object '{KEYPOINT_OBJECT_TITLE}' not found in ontology."

      # Initialise label rows
      label_rows = {}
      all_titles = [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in all_titles:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Keypoint coordinates: A single point roughly near the center
      kp = PointCoordinate(0.5, 0.5)

      # Create instances and attach to frames
      label_rows_to_save = []

      # 1. One image > frame 0
      image_lr = label_rows.get(IMAGE_TITLE)
      if image_lr is not None:
          inst: ObjectInstance = keypoint_object.create_instance()
          inst.set_for_frames(coordinates=kp, frames=0)
          image_lr.add_object_instance(inst)
          label_rows_to_save.append(image_lr)

      # 2. One image group > frame 0
      img_group_lr = label_rows.get(IMG_GROUP_TITLE)
      if img_group_lr is not None:
          inst: ObjectInstance = keypoint_object.create_instance()
          inst.set_for_frames(coordinates=kp, frames=0)
          img_group_lr.add_object_instance(inst)
          label_rows_to_save.append(img_group_lr)

      # 3. One image sequence > frame 0
      img_sequence_lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if img_sequence_lr is not None:
          inst: ObjectInstance = keypoint_object.create_instance()
          inst.set_for_frames(coordinates=kp, frames=0)
          img_sequence_lr.add_object_instance(inst)
          label_rows_to_save.append(img_sequence_lr)

      # 4. One video > reuse SAME instance across 3 consecutive frames (frames 100, 101, 102)
      video_lr = label_rows.get(VIDEO_TITLE)
      if video_lr is not None:
          inst: ObjectInstance = keypoint_object.create_instance()
          for f in [100, 101, 102]:
              inst.set_for_frames(coordinates=kp, frames=f)
          video_lr.add_object_instance(inst)
          label_rows_to_save.append(video_lr)

      # Save label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in label_rows_to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: created one keypoint on image, image group, image sequence, and 3 video frames.")

      ```

      ```python Keypoints Images/Videos expandable theme={"dark"}

      # 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",
      )

      # 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 keypoint object for floral axis
      keypoint_ontology_object: Object = ontology_structure.get_child_by_title(title="Floral axis", type_=Object)
      assert keypoint_ontology_object is not None, "Keypoint object 'Floral axis' not found in ontology"

      # Get radio attribute for floral axis type
      floral_axis_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert floral_axis_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

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

      # Get radio options
      pedicel_option = floral_axis_type_radio_attribute.get_child_by_title(type_=Option, title="Pedicel")
      assert pedicel_option is not None, "Option 'Pedicel' not found under radio attribute 'Type?'"

      peduncle_option = floral_axis_type_radio_attribute.get_child_by_title(type_=Option, title="Peduncle")
      assert peduncle_option is not None, "Option 'Peduncle' not found under radio attribute 'Type?'"

      other_floral_axis_option = floral_axis_type_radio_attribute.get_child_by_title(
          type_=Option, title="Other floral axis type"
      )
      assert other_floral_axis_option is not None, "Option 'Other floral axis type' not found under radio attribute 'Type?'"

      # Get checklist attributes and options for Pedicel
      pedicel_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Pedicel Qualities?"
      )
      assert pedicel_checklist_attribute is not None, "Checklist attribute 'Pedicel Qualities?' not found"

      pedicel_robust_option = pedicel_checklist_attribute.get_child_by_title(type_=Option, title="Robust")
      assert pedicel_robust_option is not None, "Option 'Robust' not found under 'Pedicel Qualities?'"

      pedicel_healthy_option = pedicel_checklist_attribute.get_child_by_title(type_=Option, title="Healthy")
      assert pedicel_healthy_option is not None, "Option 'Healthy' not found under 'Pedicel Qualities?'"

      pedicel_growth_alignment_option = pedicel_checklist_attribute.get_child_by_title(
          type_=Option, title="Good Growth and Alignment"
      )
      assert pedicel_growth_alignment_option is not None, (
          "Option 'Good Growth and Alignment' not found under 'Pedicel Qualities?'"
      )

      # Get checklist attributes and options for Peduncle
      peduncle_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Peduncle Qualities?"
      )
      assert peduncle_checklist_attribute is not None, "Checklist attribute 'Peduncle Qualities?' not found"

      peduncle_robust_option = peduncle_checklist_attribute.get_child_by_title(type_=Option, title="Robust")
      assert peduncle_robust_option is not None, "Option 'Robust' not found under 'Peduncle Qualities?'"

      peduncle_healthy_option = peduncle_checklist_attribute.get_child_by_title(type_=Option, title="Healthy")
      assert peduncle_healthy_option is not None, "Option 'Healthy' not found under 'Peduncle Qualities?'"

      peduncle_growth_alignment_option = peduncle_checklist_attribute.get_child_by_title(
          type_=Option, title="Good Growth and Alignment"
      )
      assert peduncle_growth_alignment_option is not None, (
          "Option 'Good Growth and Alignment' not found under 'Peduncle Qualities?'"
      )

      # Get text attribute for specifying other floral axis types
      other_floral_axis_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify floral axis type"
      )
      assert other_floral_axis_option_text_attribute is not None, "Text attribute 'Specify floral axis type' not found"

      # Dictionary of labels per data unit and per frame with floral axis type specified, including quality options
      video_image_frame_labels = {
          "blueberries-001.jpg": {
              0: {
                  "label_ref": "floral_axis_001",
                  "coordinates": PointCoordinate(x=0.01, y=0.02),
                  "floral_axis_type": "Pedicel",
                  "pedicel_quality_options": "Robust, Healthy",
                  "quality_number": 8
              }
          },
          "persimmons-010.jpg": {
              0: [
                  {
                      "label_ref": "floral_axis_002",
                      "coordinates": PointCoordinate(x=0.03, y=0.03),
                      "floral_axis_type": "Peduncle",
                      "peduncle_quality_options": "Robust, Healthy, Good Growth and Alignment",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "floral_axis_003",
                      "coordinates": PointCoordinate(x=0.05, y=0.04),
                      "floral_axis_type": "Peduncle",
                      "peduncle_quality_options": "Robust",
                      "quality_number": 5
                  },
                  {
                      "label_ref": "floral_axis_004",
                      "coordinates": PointCoordinate(x=0.09, y=0.03),
                      "floral_axis_type": "Other floral axis type",
                      "Specify floral axis type": "Calyx",
                      "quality_number": 4
                  },
              ],
          },
          "blueberries-ig": {
              0: {
                  "label_ref": "floral_axis_005",
                  "coordinates": PointCoordinate(x=0.05, y=0.02),
                  "floral_axis_type": "Pedicel",
                  "pedicel_quality_options": "Robust, Healthy",
                  "quality_number": 7
              },
              2: [
                  {
                      "label_ref": "floral_axis_006",
                      "coordinates": PointCoordinate(x=0.03, y=0.03),
                      "floral_axis_type": "Pedicel",
                      "pedicel_quality_options": "Good Growth and Alignment",
                      "quality_number": 4
                  },
                  {
                      "label_ref": "floral_axis_007",
                      "coordinates": PointCoordinate(x=0.04, y=0.05),
                      "floral_axis_type": "Pedicel",
                      "pedicel_quality_options": "Robust",
                      "quality_number": 3
                  },
                  {
                      "label_ref": "floral_axis_008",
                      "coordinates": PointCoordinate(x=0.11, y=0.02),
                      "floral_axis_type": "Other floral axis type",
                      "Specify floral axis type": "Calyx",
                      "quality_number": 3
                  },
              ],
          },
          "persimmons-is": {
              0: {
                  "label_ref": "floral_axis_009",
                  "coordinates": PointCoordinate(x=0.01, y=0.02),
                  "floral_axis_type": "Peduncle",
                  "peduncle_quality_options": "Robust",
                  "quality_number": 5
              },
              3: [
                  {
                      "label_ref": "floral_axis_010",
                      "coordinates": PointCoordinate(x=0.03, y=0.03),
                      "floral_axis_type": "Peduncle",
                      "peduncle_quality_options": "Robust, Healthy, Good Growth and Alignment",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "floral_axis_011",
                      "coordinates": PointCoordinate(x=0.08, y=0.05),
                      "floral_axis_type": "Peduncle",
                      "peduncle_quality_options": "Robust",
                      "quality_number": 2
                  },
                  {
                      "label_ref": "floral_axis_012",
                      "coordinates": PointCoordinate(x=0.11, y=0.02),
                      "floral_axis_type": "Other floral axis type",
                      "Specify floral axis type": "Calyx",
                      "quality_number": 1
                  },
              ],
          },
          "blueberries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "floral_axis_013",
                      "coordinates": PointCoordinate(x=0.02, y=0.01),
                      "floral_axis_type": "Pedicel",
                      "pedicel_quality_options": "Robust",
                      "quality_number": 5
                  },
                  {
                      "label_ref": "floral_axis_014",
                      "coordinates": PointCoordinate(x=0.06, y=0.06),
                      "floral_axis_type": "Pedicel",
                      "pedicel_quality_options": "Robust, Healthy, Good Growth and Alignment",
                      "quality_number": 8
                  },
                  {
                      "label_ref": "floral_axis_015",
                      "coordinates": PointCoordinate(x=0.10, y=0.01),
                      "floral_axis_type": "Other floral axis type",
                      "Specify floral axis type": "Calyx",
                      "quality_number": 7
                  },
              ],
              104: [
                  {
                      "label_ref": "floral_axis_016",
                      "coordinates": PointCoordinate(x=0.04, y=0.01),
                      "floral_axis_type": "Pedicel",
                      "pedicel_quality_options": "Robust",
                      "quality_number": 6
                  },
                  {
                      "label_ref": "floral_axis_014",
                      "coordinates": PointCoordinate(x=0.08, y=0.05),
                      "floral_axis_type": "Pedicel",
                      "pedicel_quality_options": "Robust, Healthy, Good Growth and Alignment",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "floral_axis_017",
                      "coordinates": PointCoordinate(x=0.11, y=0.02),
                      "floral_axis_type": "Other floral axis type",
                      "Specify floral axis type": "Calyx",
                      "quality_number": 6
                  },
              ],
              105: [
                  {
                      "label_ref": "floral_axis_016",
                      "coordinates": PointCoordinate(x=0.05, y=0.02),
                      "floral_axis_type": "Pedicel",
                      "pedicel_quality_options": "Robust",
                      "quality_number": 5
                  },
                  {
                      "label_ref": "floral_axis_014",
                      "coordinates": PointCoordinate(x=0.07, y=0.04),
                      "floral_axis_type": "Pedicel",
                      "pedicel_quality_options": "Robust, Healthy, Good Growth and Alignment",
                      "quality_number": 5
                  },
                  {
                      "label_ref": "floral_axis_017",
                      "coordinates": PointCoordinate(x=0.09, y=0.03),
                      "floral_axis_type": "Other floral axis type",
                      "Specify floral axis type": "Calyx",
                      "quality_number": 3
                  },
              ],
          },
      }


      # Cache initialized label rows
      label_row_map = {}

      # Step 1: Initialize all label rows using a bundle
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for data_unit in video_image_frame_labels.keys():
              label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
              assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"

              if not label_rows:
                  print(f"Skipping: No label row found for {data_unit}")
                  continue

              label_row = label_rows[0]
              label_row.initialise_labels(bundle=bundle)
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              label_row_map[data_unit] = label_row  # Cache initialized label row for later use

      # Step 2: Process all frames/annotations and prepare label rows to save
      label_rows_to_save = []

      for data_unit, frame_coordinates in video_image_frame_labels.items():
          label_row = label_row_map.get(data_unit)
          if not label_row:
              print(f"Skipping: No initialized label row found for {data_unit}")
              continue

          object_instances_by_label_ref = {}

          # Loop through the frames for the current data unit
          for frame_number, items in frame_coordinates.items():
              assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"
              if not isinstance(items, list):
                  items = [items]

              for item in items:
                  label_ref = item["label_ref"]
                  coord = item["coordinates"]
                  floral_axis_type = item["floral_axis_type"]
                  quality_number = item["quality_number"]

                  assert floral_axis_type in {
                      "Pedicel",
                      "Peduncle",
                      "Other floral axis type",
                  }, f"Unexpected floral axis type '{floral_axis_type}' in data unit '{data_unit}'"

                  # Check if label_ref already exists for reusability
                  if label_ref not in object_instances_by_label_ref:
                      keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()
                      assert keypoint_object_instance is not None, "Failed to create ObjectInstance"

                      object_instances_by_label_ref[label_ref] = keypoint_object_instance
                      checklist_attribute = None

                      # Set floral axis type attribute
                      if floral_axis_type == "Pedicel":
                          assert pedicel_option is not None, "Missing 'pedicel_option'"
                          keypoint_object_instance.set_answer(
                              attribute=floral_axis_type_radio_attribute, answer=pedicel_option
                          )
                          checklist_attribute = pedicel_checklist_attribute
                      elif floral_axis_type == "Peduncle":
                          assert peduncle_option is not None, "Missing 'peduncle_option'"
                          keypoint_object_instance.set_answer(
                              attribute=floral_axis_type_radio_attribute, answer=peduncle_option
                          )
                          checklist_attribute = peduncle_checklist_attribute
                      elif floral_axis_type == "Other floral axis type":
                          assert other_floral_axis_option is not None, "Missing 'other_floral_axis_option'"
                          keypoint_object_instance.set_answer(
                              attribute=floral_axis_type_radio_attribute, answer=other_floral_axis_option
                          )
                          text_answer = item.get("Specify floral axis type", "")
                          assert isinstance(text_answer, str), "'Specify floral axis type' must be a string"
                          keypoint_object_instance.set_answer(
                              attribute=other_floral_axis_option_text_attribute,
                              answer=text_answer,
                          )

                      # Set quality attribute 
                      keypoint_object_instance.set_answer(attribute=quality_number_attribute, answer=quality_number)

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

                      for quality in quality_options:
                          if quality == "Robust":
                              checklist_answers.append(
                                  pedicel_robust_option if floral_axis_type == "Pedicel" else peduncle_robust_option
                              )
                          elif quality == "Healthy":
                              checklist_answers.append(
                                  pedicel_healthy_option if floral_axis_type == "Pedicel" else peduncle_healthy_option
                              )
                          elif quality == "Good Growth and Alignment":
                              checklist_answers.append(
                                  pedicel_growth_alignment_option
                                  if floral_axis_type == "Pedicel"
                                  else peduncle_growth_alignment_option
                              )

                      if checklist_attribute and checklist_answers:
                          keypoint_object_instance.set_answer(
                              attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                          )
                  else:
                      # Reuse existing instance across frames
                      keypoint_object_instance = object_instances_by_label_ref[label_ref]

                  # Assign the object to the frame and track it
                  keypoint_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

          # Add object instances to label_row **only if they have frames assigned**
          for keypoint_object_instance in object_instances_by_label_ref.values():
              assert isinstance(keypoint_object_instance, ObjectInstance), "Expected ObjectInstance type"
              if keypoint_object_instance.get_annotation_frames():
                  label_row.add_object_instance(keypoint_object_instance)

          label_rows_to_save.append(label_row)

      # Step 3: Save all label rows using a bundle
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for label_row in label_rows_to_save:
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)
              print(f"Saved label row for {label_row.data_title}")

      print("Labels with floral axis type radio buttons, checklist attributes, number attributes, and text labels added for all data units.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Circle">
    Use `CircleCoordinates(center_x=0.XX, center_y=0.YY, radius=0.XX)` to specify the location and size of the Circle object label you want to import.

    <CodeGroup>
      ```python Image theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.objects import Object, OntologyStructure
      from encord.objects.coordinates import CircleCoordinates

      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 Project ID
      DATA_TITLE = "image_001.jpg" # Replace with the name of the image
      ONTOLOGY_OBJECT_TITLE = "Defect" # Replace with the name of the Circle object label

      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",
      )

      project = user_client.get_project(PROJECT_ID)

      (label_row,) = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
      label_row.initialise_labels()

      ontology_structure: OntologyStructure = label_row.ontology_structure
      circle_ontology_object: Object = ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      circle_object_instance = circle_ontology_object.create_instance()
      circle_object_instance.set_for_frames(
          coordinates=CircleCoordinates(center_x=0.5, center_y=0.5, radius=0.1),
          frames=0,
      )

      label_row.add_object_instance(circle_object_instance)
      label_row.save()
      ```

      ```python Image Group theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.objects import Object, OntologyStructure
      from encord.objects.coordinates import CircleCoordinates

      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 Project ID
      DATA_TITLE = "image_group_001" # Replace with the name of the image group
      ONTOLOGY_OBJECT_TITLE = "Defect" # Replace with the name of the Circle object label

      IMAGE_INDEX = 2 # Frame number of the image inside the image group (0 = first image)

      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",
      )

      project = user_client.get_project(PROJECT_ID)

      (label_row,) = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
      label_row.initialise_labels()

      ontology_structure: OntologyStructure = label_row.ontology_structure
      circle_ontology_object: Object = ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      circle_object_instance = circle_ontology_object.create_instance()
      circle_object_instance.set_for_frames(
          coordinates=CircleCoordinates(center_x=0.5, center_y=0.5, radius=0.1),
          frames=IMAGE_INDEX,
      )

      label_row.add_object_instance(circle_object_instance)
      label_row.save()
      ```

      ```python Image Sequence theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.objects import Object, OntologyStructure
      from encord.objects.coordinates import CircleCoordinates

      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 Project ID
      DATA_TITLE = "image_sequence_001" # Replace with the name of the Image Sequence
      ONTOLOGY_OBJECT_TITLE = "Defect" # Replace with the name of the Circle object label

      FRAME_INDEX = 5 # Frame number of the image inside the image sequence (0 = first image)

      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",
      )

      project = user_client.get_project(PROJECT_ID)

      (label_row,) = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
      label_row.initialise_labels()

      ontology_structure: OntologyStructure = label_row.ontology_structure
      circle_ontology_object: Object = ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      circle_object_instance = circle_ontology_object.create_instance()
      circle_object_instance.set_for_frames(
          coordinates=CircleCoordinates(center_x=0.5, center_y=0.5, radius=0.1),
          frames=FRAME_INDEX,
      )

      label_row.add_object_instance(circle_object_instance)
      label_row.save()
      ```

      ```python Video theme={"dark"}
      # Import dependencies
      from encord import EncordUserClient
      from encord.objects import Object, OntologyStructure
      from encord.objects.coordinates import CircleCoordinates
      from encord.objects.frames import Range

      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 Project ID
      DATA_TITLE = "video_001.mp4" # Replace with the name of the video
      ONTOLOGY_OBJECT_TITLE = "Defect" # Replace with the name of the Circle object label

      FRAME_RANGE = Range(start=10, end=12) # A range of three video frames: 10, 11, 12 to import the label.

      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",
      )

      project = user_client.get_project(PROJECT_ID)

      (label_row,) = project.list_label_rows_v2(data_title_eq=DATA_TITLE)
      label_row.initialise_labels()

      ontology_structure: OntologyStructure = label_row.ontology_structure
      circle_ontology_object: Object = ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      circle_object_instance = circle_ontology_object.create_instance()
      circle_object_instance.set_for_frames(
          coordinates=CircleCoordinates(center_x=0.5, center_y=0.5, radius=0.1),
          frames=FRAME_RANGE,
      )

      label_row.add_object_instance(circle_object_instance)
      label_row.save()
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Bitmask">
    **Basic**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling

    **Advanced**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling
    * Radio button options
    * Checklist options
    * Text input
    * Number input

    **Bitmask Ontology**

    ![Bitmask Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/labels-bitmaks-apples.png)

    <CodeGroup>
      ```python Bitmasks Images/Videos - Basic expandable theme={"dark"}

      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates
      import numpy as np

      # User input
      SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with your SSH private key
      PROJECT_ID = "00000000-0000-0000-0000-000000000000"   # Replace with your Project ID
      BUNDLE_SIZE = 10

      # Data unit titles in your Project
      IMAGE_TITLE = "apples-001.jpg"
      IMG_GROUP_TITLE = "apples-ig"
      IMG_SEQUENCE_TITLE = "apples-is"
      VIDEO_TITLE = "apples-vid-001.mp4"

      # Fixed frame size
      FRAME_H, FRAME_W = 1080, 1920

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Find the bitmask object "Apples" in the ontology
      ontology_structure = project.ontology_structure
      bitmask_ontology_object: Object = ontology_structure.get_child_by_title(title="Apples", type_=Object)
      assert bitmask_ontology_object is not None, "Bitmask object 'Apples' not found in ontology."

      # Initialise label rows
      label_rows = {}
      all_titles = [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]

      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in all_titles:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Prepare boolean masks with shape matching frame size
      mask_a_arr = np.ones((FRAME_H, FRAME_W), dtype=bool)
      assert mask_a_arr.shape == (FRAME_H, FRAME_W), "Mask dimensions must match 1080x1920"

      mask_b_arr = np.zeros((FRAME_H, FRAME_W), dtype=bool)
      mask_b_arr[0:FRAME_H//3, 0:FRAME_W//3] = True
      assert mask_b_arr.shape == (FRAME_H, FRAME_W), "Mask dimensions must match 1080x1920"

      mask_c_arr = np.zeros((FRAME_H, FRAME_W), dtype=bool)
      mask_c_arr[FRAME_H//4:FRAME_H//2, FRAME_W//4:FRAME_W//2] = True
      assert mask_c_arr.shape == (FRAME_H, FRAME_W), "Mask dimensions must match 1080x1920"

      mask_a = BitmaskCoordinates(mask_a_arr)
      mask_b = BitmaskCoordinates(mask_b_arr)
      mask_c = BitmaskCoordinates(mask_c_arr)

      # Create instances and attach to frames
      label_rows_to_save = []

      # 1. One image > annotate frame 0
      image_lr = label_rows.get(IMAGE_TITLE)
      if image_lr is not None:
          inst: ObjectInstance = bitmask_ontology_object.create_instance()
          inst.set_for_frames(coordinates=mask_a, frames=0, manual_annotation=True)
          image_lr.add_object_instance(inst)
          label_rows_to_save.append(image_lr)

      # 2. One image group > annotate frame 0
      img_group_lr = label_rows.get(IMG_GROUP_TITLE)
      if img_group_lr is not None:
          inst: ObjectInstance = bitmask_ontology_object.create_instance()
          inst.set_for_frames(coordinates=mask_b, frames=0, manual_annotation=True)
          img_group_lr.add_object_instance(inst)
          label_rows_to_save.append(img_group_lr)

      # 3. One image sequence > annotate frame 0
      img_sequence_lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if img_sequence_lr is not None:
          inst: ObjectInstance = bitmask_ontology_object.create_instance()
          inst.set_for_frames(coordinates=mask_c, frames=0, manual_annotation=True)
          img_sequence_lr.add_object_instance(inst)
          label_rows_to_save.append(img_sequence_lr)

      # 4. One video > reuse SAME instance across 3 consecutive frames (100, 101, 102)
      video_lr = label_rows.get(VIDEO_TITLE)
      if video_lr is not None:
          inst: ObjectInstance = bitmask_ontology_object.create_instance()
          for f, bm in zip([100, 101, 102], [mask_a, mask_b, mask_c]):
              inst.set_for_frames(coordinates=bm, frames=f, manual_annotation=True)
          video_lr.add_object_instance(inst)
          label_rows_to_save.append(video_lr)

      # Save label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in label_rows_to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: created bitmasks on image, image group, image sequence, and 3 video frames for 'Apples'.")

      ```

      ```python Bitmasks Images/Videos - Advanced expandable theme={"dark"}

      # 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."

      # Create options for the radio buttons
      sugar_bee_option = apple_type_radio_attribute.get_child_by_title(type_=Option, title="Sugar Bee")
      granny_smith_option = apple_type_radio_attribute.get_child_by_title(type_=Option, title="Granny Smith")
      honey_crisp_option = apple_type_radio_attribute.get_child_by_title(type_=Option, title="Honey Crisp")
      other_apple_option = apple_type_radio_attribute.get_child_by_title(type_=Option, title="Other apple type")

      # Create checklist attributes and options for each apple type
      # Sugar Bee Qualities
      sugar_bee_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Sugar Bee Qualities?"
      )
      sugar_bee_plump_option = sugar_bee_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      sugar_bee_juicy_option = sugar_bee_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      sugar_bee_large_option = sugar_bee_checklist_attribute.get_child_by_title(type_=Option, title="Large")

      # Granny Smith Qualities
      granny_smith_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Granny Smith Qualities?"
      )
      granny_smith_plump_option = granny_smith_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      granny_smith_juicy_option = granny_smith_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      granny_smith_large_option = granny_smith_checklist_attribute.get_child_by_title(type_=Option, title="Large")

      # Honey Crisp Qualities
      honey_crisp_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Honey Crisp Qualities?"
      )
      honey_crisp_plump_option = honey_crisp_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      honey_crisp_juicy_option = honey_crisp_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      honey_crisp_large_option = honey_crisp_checklist_attribute.get_child_by_title(type_=Option, title="Large")

      # Other apple Types
      other_apple_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify apple type"
      )

      # Dictionary of labels per data unit and per frame with apple type specified, including quality options
      video_frame_labels = {
          "apples-001.jpg": {
              0: {
                  "label_ref": "apple_001",
                  "coordinates": BitmaskCoordinates(numpy_coordinates), 
                  "apple_type": "Sugar Bee", 
                  "sugar_bee_quality_options": "Plump, Juicy",
                  "apple_quality": 7
                  }
          },
          "apples-010.jpg": {
              0: [
                  {
                      "label_ref": "apple_002", 
                      "coordinates": BitmaskCoordinates(numpy_coordinates), 
                      "apple_type": "Granny Smith", 
                      "granny_smith_quality_options": "Plump, Juicy, Large",
                      "apple_quality": 9
                      },
                  {
                      "label_ref": "apple_003",
                      "coordinates": BitmaskCoordinates(numpy_coordinates), 
                      "apple_type": "Honey Crisp", 
                      "honey_crisp_quality_options": "Plump",
                      "apple_quality": 8
                      },
                  {
                      "label_ref": "apple_004", 
                      "coordinates": BitmaskCoordinates(numpy_coordinates), 
                      "apple_type": "Other apple type", "Specify apple type": "Fuji",
                      "apple_quality": 4
                      },
              ],
          },
          "apples-ig": {
              0: {
                  "label_ref": "apple_005", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates), 
                  "apple_type": "Sugar Bee", 
                  "sugar_bee_quality_options": "Plump, Juicy",
                  "apple_quality": 7
                  },
              2: [
                  {
                  "label_ref": "apple_006", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Granny Smith", 
                  "granny_smith_quality_options": "Large",
                  "apple_quality": 6
                  },
                  {
                  "label_ref": "apple_007", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates), 
                  "apple_type": "Honey Crisp", 
                  "honey_crisp_quality_options": "Plump",
                  "apple_quality": 3
                  },
                  {
                  "label_ref": "apple_008", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Other apple type", 
                  "Specify apple type": "Jazz",
                  "apple_quality": 6
                  },
              ]
          },
          "apples-is": {
              0: {
                  "label_ref": "apple_009", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Sugar Bee", 
                  "sugar_bee_quality_options": "Plump",
                  "apple_quality": 5
                  },
              3: [
                  {
                  "label_ref": "apple_010", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates), 
                  "apple_type": "Granny Smith", 
                  "granny_smith_quality_options": "Plump, Juicy, Large",
                  "apple_quality": 9
                  },
                  {
                  "label_ref": "apple_011", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates), 
                  "apple_type": "Honey Crisp", 
                  "honey_crisp_quality_options": "Plump",
                  "apple_quality": 8
                  },
                  {
                  "label_ref": "apple_012", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates), 
                  "apple_type": "Other apple type", 
                  "Specify apple type": "Red Delicious",
                  "apple_quality": 8
                  },
              ]
          },
          "apples-vid-001.mp4": {
              103: [
                  {
                  "label_ref": "apple_013", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Honey Crisp", 
                  "honey_crisp_quality_options": "Plump",
                  "apple_quality": 4
                  },
                  {
                  "label_ref": "apple_014", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Sugar Bee", 
                  "sugar_bee_quality_options": "Plump, Juicy, Large",
                  "apple_quality": 9
                  },
                  {
                  "label_ref": "apple_015", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Other apple type", 
                  "Specify apple type": "Jazz",
                  "apple_quality": 4
                  },
              ],
              104: [
                  {
                  "label_ref": "apple_016", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates), 
                  "apple_type": "Honey Crisp", 
                  "honey_crisp_quality_options": "Plump",
                  "apple_quality": 4
                  },
                  {
                  "label_ref": "apple_014", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Sugar Bee", 
                  "sugar_bee_quality_options": "Plump, Juicy, Large",
                  "apple_quality": 9
                  },
                  {
                  "label_ref": "apple_017", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Other apple type",
                  "Specify apple type": "Fuji",
                  "apple_quality": 8
                  },
              ],
              105: [
                  {
                  "label_ref": "apple_016", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates), 
                  "apple_type": "Honey Crisp", 
                  "honey_crisp_quality_options": "Plump",
                  "apple_quality": 4
                  },
                  {
                  "label_ref": "apple_014", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Sugar Bee", 
                  "sugar_bee_quality_options": "Plump, Juicy, Large",
                  "apple_quality": 9
                  },
                  {
                  "label_ref": "apple_017", 
                  "coordinates": BitmaskCoordinates(numpy_coordinates),
                  "apple_type": "Other apple type",
                  "Specify apple type": "Red Delicious",
                  "apple_quality": 7
                  },
              ],
          },
      }


      # Loop through each data unit (image, video, etc.)
      for data_unit, frame_coordinates in video_frame_labels.items():
          object_instances_by_label_ref = {}

          # Get the label row for the current data unit
          label_row = project.list_label_rows_v2(data_title_eq=data_unit)[0]
          label_row.initialise_labels()

          # Loop through the frames for the current data unit
          for frame_number, items in frame_coordinates.items():
              if not isinstance(items, list):  #  Multiple objects in the frame
                  items = [items]

              for item in items:
                  label_ref = item["label_ref"]
                  coord = item["coordinates"]
                  apple_type = item["apple_type"]
                  apple_quality = item["apple_quality"]

                  #  Check if label_ref already exists for reusability
                  if label_ref not in object_instances_by_label_ref:
                      bitmask_object_instance: ObjectInstance = bitmask_ontology_object.create_instance()
                      object_instances_by_label_ref[label_ref] = bitmask_object_instance  #  Store for reuse
                      checklist_attribute = None

                      # Set apple quality attribute 
                      bitmask_object_instance.set_answer(attribute=apple_quality_number_attribute, answer=apple_quality)

                      # Set apple type attribute
                      if apple_type == "Sugar Bee":
                          bitmask_object_instance.set_answer(attribute=apple_type_radio_attribute, answer=sugar_bee_option)
                          checklist_attribute = sugar_bee_checklist_attribute
                      elif apple_type == "Granny Smith":
                          bitmask_object_instance.set_answer(attribute=apple_type_radio_attribute, answer=granny_smith_option)
                          checklist_attribute = granny_smith_checklist_attribute
                      elif apple_type == "Honey Crisp":
                          bitmask_object_instance.set_answer(attribute=apple_type_radio_attribute, answer=honey_crisp_option)
                          checklist_attribute = honey_crisp_checklist_attribute
                      elif apple_type == "Other apple type":
                          bitmask_object_instance.set_answer(attribute=apple_type_radio_attribute, answer=other_apple_option)
                          bitmask_object_instance.set_answer(attribute=other_apple_option_text_attribute, answer=item.get("Specify apple type", ""))

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

                      for quality in quality_options:
                          if quality == "Plump":
                              checklist_answers.append(sugar_bee_plump_option if apple_type == "Sugar Bee" else granny_smith_plump_option if apple_type == "Granny Smith" else honey_crisp_plump_option)
                          elif quality == "Juicy":
                              checklist_answers.append(sugar_bee_juicy_option if apple_type == "Sugar Bee" else granny_smith_juicy_option if apple_type == "Granny Smith" else honey_crisp_juicy_option)
                          elif quality == "Large":
                              checklist_answers.append(sugar_bee_large_option if apple_type == "Sugar Bee" else granny_smith_large_option if apple_type == "Granny Smith" else honey_crisp_large_option)

                      if checklist_attribute and checklist_answers:
                          bitmask_object_instance.set_answer(attribute=checklist_attribute, answer=checklist_answers, overwrite=True)

                  else:
                      #  Reuse existing instance across frames
                      bitmask_object_instance = object_instances_by_label_ref[label_ref]

                  #  Assign the object to the frame and track it
                  bitmask_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

          #  Add object instances to label_row **only if they have frames assigned**
          for bitmask_object_instance in object_instances_by_label_ref.values():
              if bitmask_object_instance.get_annotation_frames():  #  Ensures it has at least one frame
                  label_row.add_object_instance(bitmask_object_instance)

          #  Upload all labels for this data unit (video/image) to the server
          label_row.save()

      print(" Labels with apple type radio buttons, checklist attributes, number attributes, and text labels added for all data units.")
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Object Primitives">
    <Info>Before you can import Object Primitive labels into Encord, the Object Primitive Template MUST exist in Encord. [Use the UI to create the Object Primitive Template](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#object-primitives) so you can visually inspect the Object Primitive.</Info>

    **Import Object Primitive labels**

    **Basic**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling

    **Advanced**

    This example includes the following:

    * Single image labeling
    * Image Group labeling
    * Image Sequence labeling
    * Video labeling
    * Radio button options
    * Checklist options
    * Text input
    * Number input

    **Primitives Ontology**

    The title for the primitive object is *Triangle*.

    ![Primitive Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/labels-primitives-strawberries.png)

    <CodeGroup>
      ```python Primitives Images/Videos - Basic expandable theme={"dark"}

      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

      # 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 Project ID
      BUNDLE_SIZE = 10

      IMAGE_TITLE = "cherries-001.jpg"
      IMG_GROUP_TITLE = "cherries-ig"
      IMG_SEQUENCE_TITLE = "cherries-is"
      VIDEO_TITLE = "cherries-vid-001.mp4"

      # Authorize connection to Encord
      user_client: EncordUserClient = 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",
      )

      project: Project = user_client.get_project(PROJECT_ID)

      # Ontology pieces
      ontology = project.ontology_structure
      skeleton_object: Object = ontology.get_child_by_title(title="Strawberries", type_=Object)
      assert skeleton_object is not None, "Ontology object 'Strawberries' not found."

      # The primitive template your object uses
      assert "Triangle" in ontology.skeleton_templates, "Skeleton template 'Triangle' not found in ontology."
      template: SkeletonTemplate = ontology.skeleton_templates["Triangle"]

      # Grab the point ids defined by the template
      point_ids = [pt.feature_hash for pt in template.skeleton.values()]
      assert len(point_ids) >= 3, "Template 'Triangle' should have at least 3 points."

      # Coordinate set
      tri_coords = SkeletonCoordinates(
          values=[
              SkeletonCoordinate(x=0.30, y=0.30, name="point_0", color="#000000", value="point_0", feature_hash=point_ids[0]),
              SkeletonCoordinate(x=0.45, y=0.30, name="point_1", color="#000000", value="point_1", feature_hash=point_ids[1]),
              SkeletonCoordinate(x=0.35, y=0.45, name="point_2", color="#000000", value="point_2", feature_hash=point_ids[2]),
          ],
          name="Triangle",
      )

      # Initialize label rows
      label_rows = {}
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for title in [IMAGE_TITLE, IMG_GROUP_TITLE, IMG_SEQUENCE_TITLE, VIDEO_TITLE]:
              rows = project.list_label_rows_v2(data_title_eq=title)
              assert isinstance(rows, list), f"Expected list for '{title}', got {type(rows)}"
              if not rows:
                  print(f"Skipping: No label row found for {title}")
                  continue
              lr = rows[0]
              lr.initialise_labels(bundle=bundle)
              assert lr.ontology_structure is not None, f"Ontology not initialized for '{title}'"
              label_rows[title] = lr

      # Create one skeleton instance per data unit and assign frames
      to_save = []

      # 1. One image > frame 0
      lr = label_rows.get(IMAGE_TITLE)
      if lr:
          inst: ObjectInstance = skeleton_object.create_instance()
          inst.set_for_frames(coordinates=tri_coords, frames=0)
          lr.add_object_instance(inst)
          to_save.append(lr)

      # 2. One image group > frame 0
      lr = label_rows.get(IMG_GROUP_TITLE)
      if lr:
          inst: ObjectInstance = skeleton_object.create_instance()
          inst.set_for_frames(coordinates=tri_coords, frames=0)
          lr.add_object_instance(inst)
          to_save.append(lr)

      # 3. One image sequence > frame 0
      lr = label_rows.get(IMG_SEQUENCE_TITLE)
      if lr:
          inst: ObjectInstance = skeleton_object.create_instance()
          inst.set_for_frames(coordinates=tri_coords, frames=0)
          lr.add_object_instance(inst)
          to_save.append(lr)

      # 4. One video > reuse same instance across 3 consecutive frames
      lr = label_rows.get(VIDEO_TITLE)
      if lr:
          inst: ObjectInstance = skeleton_object.create_instance()
          for f in [100, 101, 102]:
              inst.set_for_frames(coordinates=tri_coords, frames=f)
          lr.add_object_instance(inst)
          to_save.append(lr)

      # Save label rows
      with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
          for lr in to_save:
              lr.save(bundle=bundle)
              print(f"Saved label row for {lr.data_title}")

      print("Done: placed a minimal 'Strawberries' skeleton (Triangle) on image, image group, image sequence, and 3 video frames.")

      ```

      ```python Primitives Images/Videos - Advanced expandable theme={"dark"}

      # 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 SkeletonCoordinate, SkeletonCoordinates
      from encord.objects.skeleton_template import SkeletonTemplate
      from encord.objects.attributes import NumericAttribute

      # 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"
      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 from the project"

      # Get the skeleton annotation object
      skeleton_ontology_object: Object = ontology_structure.get_child_by_title(title="Strawberries", type_=Object)
      assert skeleton_ontology_object is not None, "Object 'Strawberries' not found in ontology"

      # Get skeleton template
      assert "Triangle" in project.ontology_structure.skeleton_templates, "Skeleton template 'Triangle' not found"
      skeleton_template: SkeletonTemplate = project.ontology_structure.skeleton_templates["Triangle"]
      assert skeleton_template is not None, "Skeleton template 'Triangle' is None"

      # Get skeleton point IDs
      skeleton_ids = [coord.feature_hash for coord in skeleton_template.skeleton.values()]
      assert skeleton_ids, "Skeleton template 'Triangle' has no keypoints"

      # Get radio attribute for strawberry type
      strawberry_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
      assert strawberry_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

      # Get radio options
      albion_option = strawberry_type_radio_attribute.get_child_by_title(type_=Option, title="Albion")
      assert albion_option is not None, "Option 'Albion' not found under 'Type?'"

      redcoat_option = strawberry_type_radio_attribute.get_child_by_title(type_=Option, title="Redcoat")
      assert redcoat_option is not None, "Option 'Redcoat' not found under 'Type?'"

      sweet_kiss_option = strawberry_type_radio_attribute.get_child_by_title(type_=Option, title="Sweet Kiss")
      assert sweet_kiss_option is not None, "Option 'Sweet Kiss' not found under 'Type?'"

      other_strawberry_option = strawberry_type_radio_attribute.get_child_by_title(
          type_=Option, title="Other strawberry type"
      )
      assert other_strawberry_option is not None, "Option 'Other strawberry type' not found under 'Type?'"

      # Albion Qualities
      albion_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Albion Qualities?")
      assert albion_checklist_attribute is not None, "Checklist attribute 'Albion Qualities?' not found"

      albion_plump_option = albion_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert albion_plump_option is not None, "Option 'Plump' not found under 'Albion Qualities?'"

      albion_juicy_option = albion_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert albion_juicy_option is not None, "Option 'Juicy' not found under 'Albion Qualities?'"

      albion_large_option = albion_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert albion_large_option is not None, "Option 'Large' not found under 'Albion Qualities?'"

      # Redcoat Qualities
      redcoat_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Redcoat Qualities?"
      )
      assert redcoat_checklist_attribute is not None, "Checklist attribute 'Redcoat Qualities?' not found"

      redcoat_plump_option = redcoat_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert redcoat_plump_option is not None, "Option 'Plump' not found under 'Redcoat Qualities?'"

      redcoat_juicy_option = redcoat_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert redcoat_juicy_option is not None, "Option 'Juicy' not found under 'Redcoat Qualities?'"

      redcoat_large_option = redcoat_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert redcoat_large_option is not None, "Option 'Large' not found under 'Redcoat Qualities?'"

      # Sweet Kiss Qualities
      sweet_kiss_checklist_attribute = ontology_structure.get_child_by_title(
          type_=ChecklistAttribute, title="Sweet Kiss Qualities?"
      )
      assert sweet_kiss_checklist_attribute is not None, "Checklist attribute 'Sweet Kiss Qualities?' not found"

      sweet_kiss_plump_option = sweet_kiss_checklist_attribute.get_child_by_title(type_=Option, title="Plump")
      assert sweet_kiss_plump_option is not None, "Option 'Plump' not found under 'Sweet Kiss Qualities?'"

      sweet_kiss_juicy_option = sweet_kiss_checklist_attribute.get_child_by_title(type_=Option, title="Juicy")
      assert sweet_kiss_juicy_option is not None, "Option 'Juicy' not found under 'Sweet Kiss Qualities?'"

      sweet_kiss_large_option = sweet_kiss_checklist_attribute.get_child_by_title(type_=Option, title="Large")
      assert sweet_kiss_large_option is not None, "Option 'Large' not found under 'Sweet Kiss Qualities?'"

      # Other strawberry type (text input)
      other_strawberry_option_text_attribute = ontology_structure.get_child_by_title(
          type_=TextAttribute, title="Specify strawberry type"
      )
      assert other_strawberry_option_text_attribute is not None, "Text attribute 'Specify strawberry type' not found"

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

      # Dictionary of labels per data unit and per frame with strawberry type specified, including quality options
      video_frame_labels = {
          "strawberries-001.jpg": {
              0: {
                  "label_ref": "strawberry_001",
                  "coordinates": SkeletonCoordinates(
                      values=[
                          SkeletonCoordinate(
                              x=0.25, y=0.25, name="point_0", color="#000000", value="point_0", feature_hash=skeleton_ids[0]
                          ),
                          SkeletonCoordinate(
                              x=0.35, y=0.25, name="point_1", color="#000000", value="point_1", feature_hash=skeleton_ids[1]
                          ),
                          SkeletonCoordinate(
                              x=0.25, y=0.35, name="point_2", color="#000000", value="point_2", feature_hash=skeleton_ids[2]
                          ),
                      ],
                      name="Triangle",
                  ),
                  "strawberry_type": "Albion",
                  "albion_quality_options": "Plump, Juicy",
                  "quality_number": 8
              }
          },
          "strawberries-010.jpg": {
              0: [
                  {
                      "label_ref": "strawberry_002",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.25,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.35,
                                  y=0.25,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.35,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Redcoat",
                      "redcoat_quality_options": "Plump, Juicy, Large",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "strawberry_003",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.45,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.55,
                                  y=0.45,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.55,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Sweet Kiss",
                      "sweet_kiss_quality_options": "Plump",
                      "quality_number": 7
                  },
                  {
                      "label_ref": "strawberry_004",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.65,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.75,
                                  y=0.65,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.75,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Other strawberry type",
                      "Specify strawberry type": "Pineberry",
                      "quality_number": 4
                  },
              ],
          },
          "strawberries-ig": {
              0: {
                  "label_ref": "strawberry_005",
                  "coordinates": SkeletonCoordinates(
                      values=[
                          SkeletonCoordinate(
                              x=0.25, y=0.25, name="point_0", color="#000000", value="point_0", feature_hash=skeleton_ids[0]
                          ),
                          SkeletonCoordinate(
                              x=0.35, y=0.25, name="point_1", color="#000000", value="point_1", feature_hash=skeleton_ids[1]
                          ),
                          SkeletonCoordinate(
                              x=0.25, y=0.35, name="point_2", color="#000000", value="point_2", feature_hash=skeleton_ids[2]
                          ),
                      ],
                      name="Triangle",
                  ),
                  "strawberry_type": "Albion",
                  "albion_quality_options": "Plump, Juicy",
                  "quality_number": 8
              },
              2: [
                  {
                      "label_ref": "strawberry_006",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.25,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.35,
                                  y=0.25,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.35,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Redcoat",
                      "redcoat_quality_options": "Large",
                      "quality_number": 6
                  },
                  {
                      "label_ref": "strawberry_007",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.45,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.55,
                                  y=0.45,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.55,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Sweet Kiss",
                      "sweet_kiss_quality_options": "Plump",
                      "quality_number": 5
                  },
                  {
                      "label_ref": "strawberry_008",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.65,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.75,
                                  y=0.65,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.75,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Other strawberry type",
                      "Specify strawberry type": "Pineberry",
                      "quality_number": 7
                  },
              ],
          },
          "strawberries-is": {
              0: {
                  "label_ref": "strawberry_009",
                  "coordinates": SkeletonCoordinates(
                      values=[
                          SkeletonCoordinate(
                              x=0.25, y=0.25, name="point_0", color="#000000", value="point_0", feature_hash=skeleton_ids[0]
                          ),
                          SkeletonCoordinate(
                              x=0.35, y=0.25, name="point_1", color="#000000", value="point_1", feature_hash=skeleton_ids[1]
                          ),
                          SkeletonCoordinate(
                              x=0.25, y=0.35, name="point_2", color="#000000", value="point_2", feature_hash=skeleton_ids[2]
                          ),
                      ],
                      name="Triangle",
                  ),
                  "strawberry_type": "Albion",
                  "albion_quality_options": "Plump",
                  "quality_number": 4
              },
              3: [
                  {
                      "label_ref": "strawberry_010",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.25,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.35,
                                  y=0.25,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.35,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Redcoat",
                      "redcoat_quality_options": "Plump, Juicy, Large",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "strawberry_011",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.45,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.55,
                                  y=0.45,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.55,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Sweet Kiss",
                      "sweet_kiss_quality_options": "Plump",
                      "quality_number": 7
                  },
                  {
                      "label_ref": "strawberry_012",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.65,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.75,
                                  y=0.65,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.75,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Other strawberry type",
                      "Specify strawberry type": "Pineberry",
                      "quality_number": 7
                  },
              ],
          },
          "strawberries-vid-001.mp4": {
              103: [
                  {
                      "label_ref": "strawberry_013",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.25,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.35,
                                  y=0.25,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.35,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Sweet Kiss",
                      "sweet_kiss_quality_options": "Plump",
                      "quality_number": 7
                  },
                  {
                      "label_ref": "strawberry_014",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.45,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.55,
                                  y=0.45,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.55,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Albion",
                      "albion_quality_options": "Plump, Juicy, Large",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "strawberry_015",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.65,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.75,
                                  y=0.65,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.75,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Other strawberry type",
                      "Specify strawberry type": "Pineberry",
                      "quality_number": 6
                  },
              ],
              104: [
                  {
                      "label_ref": "strawberry_016",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.15,
                                  y=0.15,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.25,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.15,
                                  y=0.15,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Sweet Kiss",
                      "sweet_kiss_quality_options": "Plump",
                      "quality_number": 8
                  },
                  {
                      "label_ref": "strawberry_014",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.35,
                                  y=0.35,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.35,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.35,
                                  y=0.45,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Albion",
                      "albion_quality_options": "Plump, Juicy, Large",
                      "quality_number": 8
                  },
                  {
                      "label_ref": "strawberry_017",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.55,
                                  y=0.55,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.55,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.55,
                                  y=0.65,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Other strawberry type",
                      "Specify strawberry type": "Pineberry",
                      "quality_number": 7
                  },
              ],
              105: [
                  {
                      "label_ref": "strawberry_016",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.25,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.35,
                                  y=0.25,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.25,
                                  y=0.35,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Sweet Kiss",
                      "sweet_kiss_quality_options": "Plump",
                      "quality_number": 6
                  },
                  {
                      "label_ref": "strawberry_014",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.45,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.55,
                                  y=0.45,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.45,
                                  y=0.55,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Albion",
                      "albion_quality_options": "Plump, Juicy, Large",
                      "quality_number": 9
                  },
                  {
                      "label_ref": "strawberry_017",
                      "coordinates": SkeletonCoordinates(
                          values=[
                              SkeletonCoordinate(
                                  x=0.75,
                                  y=0.75,
                                  name="point_0",
                                  color="#000000",
                                  value="point_0",
                                  feature_hash=skeleton_ids[0],
                              ),
                              SkeletonCoordinate(
                                  x=0.65,
                                  y=0.75,
                                  name="point_1",
                                  color="#000000",
                                  value="point_1",
                                  feature_hash=skeleton_ids[1],
                              ),
                              SkeletonCoordinate(
                                  x=0.75,
                                  y=0.65,
                                  name="point_2",
                                  color="#000000",
                                  value="point_2",
                                  feature_hash=skeleton_ids[2],
                              ),
                          ],
                          name="Triangle",
                      ),
                      "strawberry_type": "Other strawberry type",
                      "Specify strawberry type": "Pineberry",
                      "quality_number": 5
                  },
              ],
          },
      }


      # Loop through each data unit (image, video, etc.)
      for data_unit, frame_coordinates in video_frame_labels.items():
          object_instances_by_label_ref = {}

          # Get the label row for the current data unit
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"
          assert label_rows, f"No label row found for data unit: {data_unit}"

          label_row = label_rows[0]
          assert label_row is not None, f"Label row is None for {data_unit}"

          # Initialize label row using bundle
          with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
              label_row.initialise_labels()
              assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

              for frame_number, items in frame_coordinates.items():
                  assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"
                  if not isinstance(items, list):
                      items = [items]

                  for item in items:
                      label_ref = item["label_ref"]
                      coord = item["coordinates"]
                      strawberry_type = item["strawberry_type"]
                      quality_number = item["quality_number"]

                      assert strawberry_type in {
                          "Albion",
                          "Redcoat",
                          "Sweet Kiss",
                          "Other strawberry type",
                      }, f"Unexpected strawberry type '{strawberry_type}' in data unit '{data_unit}'"

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

                          # Set quality number attribute 
                          skeleton_object_instance.set_answer(attribute=quality_number_attribute, answer=quality_number)

                          object_instances_by_label_ref[label_ref] = skeleton_object_instance
                          checklist_attribute = None

                          # Set strawberry type radio attribute
                          if strawberry_type == "Albion":
                              assert albion_option is not None, "Missing 'albion_option'"
                              skeleton_object_instance.set_answer(
                                  attribute=strawberry_type_radio_attribute, answer=albion_option
                              )
                              checklist_attribute = albion_checklist_attribute
                          elif strawberry_type == "Redcoat":
                              assert redcoat_option is not None, "Missing 'redcoat_option'"
                              skeleton_object_instance.set_answer(
                                  attribute=strawberry_type_radio_attribute, answer=redcoat_option
                              )
                              checklist_attribute = redcoat_checklist_attribute
                          elif strawberry_type == "Sweet Kiss":
                              assert sweet_kiss_option is not None, "Missing 'sweet_kiss_option'"
                              skeleton_object_instance.set_answer(
                                  attribute=strawberry_type_radio_attribute, answer=sweet_kiss_option
                              )
                              checklist_attribute = sweet_kiss_checklist_attribute
                          elif strawberry_type == "Other strawberry type":
                              assert other_strawberry_option is not None, "Missing 'other_strawberry_option'"
                              skeleton_object_instance.set_answer(
                                  attribute=strawberry_type_radio_attribute, answer=other_strawberry_option
                              )
                              text_answer = item.get("Specify strawberry type", "")
                              assert isinstance(text_answer, str), "'Specify strawberry type' must be a string"
                              skeleton_object_instance.set_answer(
                                  attribute=other_strawberry_option_text_attribute,
                                  answer=text_answer,
                              )

                          # Set checklist attributes
                          checklist_answers = []
                          quality_key = f"{strawberry_type.lower().replace(' ', '_')}_quality_options"
                          quality_options = item.get(quality_key, "").split(", ")

                          for quality in quality_options:
                              option = None
                              if quality == "Plump":
                                  option = (
                                      albion_plump_option
                                      if strawberry_type == "Albion"
                                      else redcoat_plump_option
                                      if strawberry_type == "Redcoat"
                                      else sweet_kiss_plump_option
                                      if strawberry_type == "Sweet Kiss"
                                      else None
                                  )
                              elif quality == "Juicy":
                                  option = (
                                      albion_juicy_option
                                      if strawberry_type == "Albion"
                                      else redcoat_juicy_option
                                      if strawberry_type == "Redcoat"
                                      else sweet_kiss_juicy_option
                                      if strawberry_type == "Sweet Kiss"
                                      else None
                                  )
                              elif quality == "Large":
                                  option = (
                                      albion_large_option
                                      if strawberry_type == "Albion"
                                      else redcoat_large_option
                                      if strawberry_type == "Redcoat"
                                      else sweet_kiss_large_option
                                      if strawberry_type == "Sweet Kiss"
                                      else None
                                  )

                              if option:
                                  checklist_answers.append(option)
                              else:
                                  assert strawberry_type == "Other strawberry type", (
                                      f"Invalid quality '{quality}' for strawberry type '{strawberry_type}'"
                                  )

                          if checklist_attribute and checklist_answers:
                              skeleton_object_instance.set_answer(
                                  attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                              )

                      else:
                          skeleton_object_instance = object_instances_by_label_ref[label_ref]

                      # Assign the object to the frame and track it
                      skeleton_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

              # Add object instances to label_row **only if they have frames assigned**
              for skeleton_object_instance in object_instances_by_label_ref.values():
                  assert isinstance(skeleton_object_instance, ObjectInstance), "Expected ObjectInstance type"
                  if skeleton_object_instance.get_annotation_frames():
                      label_row.add_object_instance(skeleton_object_instance)

              # Save label row using the bundle
              assert label_row is not None, "Trying to save a None label row"
              label_row.save(bundle=bundle)

      print("Labels with strawberry type radio buttons, checklist attributes, number attributes, and text labels added for all data units.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Classifications

<AccordionGroup>
  <Accordion title="Text Classification">
    The following example assumes the Ontology includes a text classification field named `Mood`. In this example, the text classification for the first label row (data unit) in the Project is set to `Melancholy` on the first frame.

    * Replace `<private_key_path>` with the key to your private key for authentication.
    * Replace `<project_hash>` with the hash of your Project.
    * Replace the Classification names and answers to suit your needs.

    ```python theme={"dark"}
    # Import dependencies
    from typing import List

    from encord import EncordUserClient
    from encord.objects import LabelRowV2, Classification, ClassificationInstance, OntologyStructure

    # Instantiate Encord client by replacing <private_key_path> with the path to your private key
    user_client = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path="<private_key_path>"
    )

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

    # For simplicity, get only the first label row
    first_label_row: List[LabelRowV2] = project.list_label_rows_v2()[0]

    # Download the existing labels 
    first_label_row.initialise_labels()

    # Get Ontology Structure
    ontology_structure: OntologyStructure = first_label_row.ontology_structure

    # Assume that the following text classification exists in the Ontology.
    text_ontology_classification: Classification = (
        ontology_structure.get_child_by_title(
            title="Mood", type_=Classification
        )
    )
    text_classification_instance = text_ontology_classification.create_instance()

    # Set the value of the classification instance
    text_classification_instance.set_answer(answer="Melancholy")

    # Select the frames where the classification instance is present. Not required for global classifications
    text_classification_instance.set_for_frames(frames=0)

    # Add it to the label row
    first_label_row.add_classification_instance(text_classification_instance)

    # Save labels
    first_label_row.save()
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Text">
    **Example 1:**

    Adds a Text classification to a specific data unit. Ensure you replace `<data-unit-name>` with the name of the data unit you want to add the classification to.

    **Example 2:**

    Adds a Text attribute to an arbitrary bounding box on a specific data unit. Ensure you replace `<data-unit-name>` with the name of the data unit you want to add the classification to, and `<project_id>` with the unique ID of the Project.

    <CodeGroup>
      ```python Example 1 theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure, Classification

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path="<private_key_path>"
      )

      project = user_client.get_project("<project_id>")

      label_row = project.list_label_rows_v2(
          data_title_eq="<data-unit-name>"
      )[0]

      label_row.initialise_labels()

      # Get Ontology Structure
      ontology_structure: OntologyStructure = label_row.ontology_structure

      # Assume that the following text classification exists in the Ontology.
      text_ontology_classification: Classification = (
          ontology_structure.get_child_by_title(
              title="Name", type_=Classification
          )
      )

      text_classification_instance = text_ontology_classification.create_instance()

      # Set the value of the classification instance
      text_classification_instance.set_answer(answer="Dexter")

      # Select the frames where the classification instance is present. Not required for global classifications
      text_classification_instance.set_for_frames(frames=0)

      # Add it to the label row
      label_row.add_classification_instance(text_classification_instance)

      # Save labels
      label_row.save()
      print('added classification instance')
      ```

      ```python Example 2 theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure, Object

      from encord.objects.attributes import TextAttribute
      from encord.objects.coordinates import BoundingBoxCoordinates

      # Instantiate Encord client by replacing <private_key_path> with the path to your private key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path="<private_key_path>"
      )

      # Get Project
      project = user_client.get_project("<project_id>")

      # Get label rows
      label_row = project.list_label_rows_v2(
          data_title_eq="<data-unit-name>"
      )[0]

      #Initialise labels
      label_row.initialise_labels()

      # Get Ontology Structure
      ontology_structure: OntologyStructure = label_row.ontology_structure

      # Define the object
      person_object: Object = ontology_structure.get_child_by_title(
                  title="Person", type_=Object
              )

      # Define the text attribute
      name_attribute = person_object.get_child_by_title("Name", type_=TextAttribute)

      # Create object instance
      person_object_instance = person_object.create_instance()

      # Add arbitrary bounding box
      person_object_instance.set_for_frames(
          coordinates=BoundingBoxCoordinates(0.5, 0.5, 0.5, 0.5),
          frames=0,
          manual_annotation=True
      )

      # Set attribute 
      person_object_instance.set_answer(
          answer="Dexter",
          attribute=name_attribute,
      )

      # Add object instance
      label_row.add_object_instance(person_object_instance)

      # Save labels 
      label_row.save()

      print('added object instance')
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Number">
    **Example 1:**

    Adds a Number input to a specific data unit. Ensure you replace `<data-unit-name>` with the name of the data unit you want to add the classification to.

    **Example 2:**

    Adds a Number attribute to an arbitrary bounding box on a specific data unit. Ensure you replace `<data-unit-name>` with the name of the data unit you want to add the classification to, and `<project_id>` with the unique ID of the Project.

    <CodeGroup>
      ```python Example 1 theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure, Classification

      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path="<private_key_path>"
      )

      project = user_client.get_project("<project_id>")

      label_row = project.list_label_rows_v2(
          data_title_eq="<data-unit-name>"
      )[0]

      label_row.initialise_labels()

      # Get Ontology Structure
      ontology_structure: OntologyStructure = label_row.ontology_structure

      # Assume that the following Number input exists in the Ontology.
      number_ontology_classification: Classification = (
          ontology_structure.get_child_by_title(
              title="Score", type_=Classification
          )
      )

      number_classification_instance = number_ontology_classification.create_instance()

      # Set the value of the classification instance
      number_classification_instance.set_answer(answer=2)

      # Select the frames where the classification instance is present. Not required for global classifications
      number_classification_instance.set_for_frames(frames=0)

      # Add it to the label row
      label_row.add_classification_instance(number_classification_instance)

      # Save labels
      label_row.save()
      print('added classification instance')
      ```

      ```python Example 2 theme={"dark"}
      from encord import EncordUserClient
      from encord.objects import OntologyStructure, Object

      from encord.objects.attributes import NumericAttribute
      from encord.objects.coordinates import BoundingBoxCoordinates

      # Instantiate Encord client by replacing <private_key_path> with the path to your private key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path="<private_key_path>"
      )

      # Get Project
      project = user_client.get_project("<project_id>")

      # Get label rows
      label_row = project.list_label_rows_v2(
          data_title_eq="<data-unit-name>"
      )[0]

      #Initialise labels
      label_row.initialise_labels()

      # Get Ontology Structure
      ontology_structure: OntologyStructure = label_row.ontology_structure

      # Define the object
      car_object: Object = ontology_structure.get_child_by_title(
                  title="Car", type_=Object
              )

      # Get the numerical attribute
      race_position_attribute = car_object.get_child_by_title("Race Position", type_=NumericAttribute)

      # Create object instance
      car_object_instance = car_object.create_instance()

      # Add arbitrary bounding box
      car_object_instance.set_for_frames(
          coordinates=BoundingBoxCoordinates(0.5, 0.5, 0.5, 0.5),
          frames=0,
          manual_annotation=True
      )

      # Set attribute answer
      car_object_instance.set_answer(
          answer=2,
          attribute=race_position_attribute,
      )

      # Add object instance
      label_row.add_object_instance(car_object_instance)

      # Save labels 
      label_row.save()

      print('added object instance')
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Radio Button">
    **Example 1:**

    Imports a Radio button options (`Blueberry or Cherry?`) to a single image (`blueberry_003.jpg`).

    **Example 2:**

    Imports a Radio button options (`Blueberry or Cherry?`) across a range of sequential frames (193 to 197) to a video (`Blueberries_video.mp4`).

    <CodeGroup>
      ```python Radio Button Template theme={"dark"}
      #Import dependencies
      from __future__ import annotations
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import (
          Classification,
      )
      from collections import defaultdict
      from copy import deepcopy
      from dataclasses import dataclass, field
      from datetime import datetime
      from typing import (
          TYPE_CHECKING,
          Any,
          Dict,
          Iterable,
          List,
          Optional,
          Sequence,
          Set,
          Tuple,
          Union,
      )
      from dateutil.parser import parse
      from encord.constants.enums import DataType
      from encord.exceptions import LabelRowError
      from encord.objects import ChecklistAttribute, RadioAttribute, TextAttribute
      from encord.objects.answers import (
          Answer,
          _get_static_answer_map,
          get_default_answer_from_attribute,
      )

      from encord.objects.frames import (
          Frames,
          Ranges,
      )
      from encord.objects.internal_helpers import (
          _infer_attribute_from_answer,
          _search_child_attributes,
      )
      from encord.objects.ontology_object import Object
      from encord.objects.options import Option
      from encord.objects.utils import check_email, short_uuid_str

      if TYPE_CHECKING:
          from encord.objects.ontology_labels_impl import LabelRowV2


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

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

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


      # Creating classification- START
      # Specify the data unit to apply classification
      label_row = project.list_label_rows_v2(
          data_title_eq="<data-unit-name>"
      )[0]

      label_row.initialise_labels()


      # Assume that the following radio classification exists in the ontology.

      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title="<classification-name>",
          type_=Classification,
      )

      blueberry_option = radio_ontology_classification.get_child_by_title(
          title="<radio-button-option-title>", type_=Option
      )

      radio_classification_instance = (
         radio_ ontology_classification.create_instance()
      )

      radio_classification_instance.set_answer(
          answer=<radio-button-option>
      )
      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)


      label_row.save()
      ```

      ```python Example 1 theme={"dark"}
      #Import dependencies
      from __future__ import annotations
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import (
          Classification,
      )
      from collections import defaultdict
      from copy import deepcopy
      from dataclasses import dataclass, field
      from datetime import datetime
      from typing import (
          TYPE_CHECKING,
          Any,
          Dict,
          Iterable,
          List,
          Optional,
          Sequence,
          Set,
          Tuple,
          Union,
      )
      from dateutil.parser import parse
      from encord.constants.enums import DataType
      from encord.exceptions import LabelRowError
      from encord.objects import ChecklistAttribute, RadioAttribute, TextAttribute
      from encord.objects.answers import (
          Answer,
          _get_static_answer_map,
          get_default_answer_from_attribute,
      )

      from encord.objects.frames import (
          Frames,
          Ranges,
      )
      from encord.objects.internal_helpers import (
          _infer_attribute_from_answer,
          _search_child_attributes,
      )
      from encord.objects.ontology_object import Object
      from encord.objects.options import Option
      from encord.objects.utils import check_email, short_uuid_str

      if TYPE_CHECKING:
          from encord.objects.ontology_labels_impl import LabelRowV2


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"

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

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


      # Creating classification- START
      # Specify the data unit to apply classification
      label_row = project.list_label_rows_v2(
          data_title_eq="blueberry_003.jpg"
      )[0]

      label_row.initialise_labels()


      # Assume that the following radio classification exists in the ontology.

      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title="Blueberry or Cherry?",
          type_=Classification,
      )

      blueberry_option = radio_ontology_classification.get_child_by_title(
          title="Blueberry", type_=Option
      )

      radio_classification_instance = (
         radio_ontology_classification.create_instance()
      )

      radio_classification_instance.set_answer(
          answer=blueberry_option
      )
      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)


      label_row.save()

      ```

      ```python Example 2 theme={"dark"}
      #Import dependencies
      from __future__ import annotations
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import (
          Classification,
      )
      from collections import defaultdict
      from copy import deepcopy
      from dataclasses import dataclass, field
      from datetime import datetime
      from typing import (
          TYPE_CHECKING,
          Any,
          Dict,
          Iterable,
          List,
          Optional,
          Sequence,
          Set,
          Tuple,
          Union,
      )
      from dateutil.parser import parse
      from encord.constants.enums import DataType
      from encord.exceptions import LabelRowError
      from encord.objects import ChecklistAttribute, RadioAttribute, TextAttribute
      from encord.objects.answers import (
          Answer,
          _get_static_answer_map,
          get_default_answer_from_attribute,
      )

      from encord.objects.frames import (
          Frames,
          Range,
          Ranges,
      )
      from encord.objects.internal_helpers import (
          _infer_attribute_from_answer,
          _search_child_attributes,
      )
      from encord.objects.ontology_object import Object
      from encord.objects.options import Option
      from encord.objects.utils import check_email, short_uuid_str

      if TYPE_CHECKING:
          from encord.objects.ontology_labels_impl import LabelRowV2


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"

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

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


      # Creating Checklist options- START
      # Specify the data unit to add classification
      label_row = project.list_label_rows_v2(
          data_title_eq="Blueberries_video.mp4"
      )[0]

      label_row.initialise_labels()


      # Assume that the following radio classification exists in the ontology.

      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title="Blueberry or Cherry?",
          type_=Classification,
      )

      blueberry_option = radio_ontology_classification.get_child_by_title(
          title="Blueberry", type_=Option
      )

      radio_classification_instance = (
          radio_ontology_classification.create_instance()
      )

      radio_classification_instance.set_answer(
          answer=blueberry_option,

      )
      radio_classification_instance.set_for_frames(
          frames=Range(start=160, end=165),
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      label_row.add_classification_instance(radio_classification_instance)


      label_row.save()
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Checklist">
    **Example 1:**

    Imports a Checklist options (`Many types of fruit?`) to a single image (`apple_003.jpg`). The selected items from the list are `apple` and `kiwi`.

    **Example 2:**

    Imports a Checklist options (`Many types of fruit?`) across a range of sequential frames: 193 to 197) to a video (`Blueberries_video.mp4`). The selected items from the list are `apple` and `kiwi`.

    <CodeGroup>
      ```python Checklist Template theme={"dark"}
      #Import dependencies
      from __future__ import annotations
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import (
          Classification,
      )
      from collections import defaultdict
      from copy import deepcopy
      from dataclasses import dataclass, field
      from datetime import datetime
      from typing import (
          TYPE_CHECKING,
          Any,
          Dict,
          Iterable,
          List,
          Optional,
          Sequence,
          Set,
          Tuple,
          Union,
      )
      from dateutil.parser import parse
      from encord.constants.enums import DataType
      from encord.exceptions import LabelRowError
      from encord.objects import ChecklistAttribute, RadioAttribute, TextAttribute
      from encord.objects.answers import (
          Answer,
          _get_static_answer_map,
          get_default_answer_from_attribute,
      )

      from encord.objects.frames import (
          Frames,
          Ranges,
      )
      from encord.objects.internal_helpers import (
          _infer_attribute_from_answer,
          _search_child_attributes,
      )
      from encord.objects.ontology_object import Object
      from encord.objects.options import Option
      from encord.objects.utils import check_email, short_uuid_str

      if TYPE_CHECKING:
          from encord.objects.ontology_labels_impl import LabelRowV2


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"

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

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


      # Creating one polyline- START
      label_row = project.list_label_rows_v2(
          data_title_eq="Blueberries_video.mp4"
      )[0]

      label_row.initialise_labels()


      # Assume that the following radio classification exists in the ontology.

      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title="Many types of fruit?",
          type_=Classification,
      )

      apple_option = checklist_ontology_classification.get_child_by_title(
          title="Apple", type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title="Kiwi", type_=Option
      )
      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)


      label_row.save()

      ```

      ```python Example 1 theme={"dark"}
      #Import dependencies
      from __future__ import annotations
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import (
          Classification,
      )
      from collections import defaultdict
      from copy import deepcopy
      from dataclasses import dataclass, field
      from datetime import datetime
      from typing import (
          TYPE_CHECKING,
          Any,
          Dict,
          Iterable,
          List,
          Optional,
          Sequence,
          Set,
          Tuple,
          Union,
      )
      from dateutil.parser import parse
      from encord.constants.enums import DataType
      from encord.exceptions import LabelRowError
      from encord.objects import ChecklistAttribute, RadioAttribute, TextAttribute
      from encord.objects.answers import (
          Answer,
          _get_static_answer_map,
          get_default_answer_from_attribute,
      )

      from encord.objects.frames import (
          Frames,
          Ranges,
      )
      from encord.objects.internal_helpers import (
          _infer_attribute_from_answer,
          _search_child_attributes,
      )
      from encord.objects.ontology_object import Object
      from encord.objects.options import Option
      from encord.objects.utils import check_email, short_uuid_str

      if TYPE_CHECKING:
          from encord.objects.ontology_labels_impl import LabelRowV2


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"

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

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


      # Creating Checklist options- START
      # Specify the data unit to add classification
      label_row = project.list_label_rows_v2(
          data_title_eq="apple_003.jpg"
      )[0]

      label_row.initialise_labels()


      # Assume that the following Checklist options exists in the ontology.

      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title="Many types of fruit?",
          type_=Classification,
      )

      apple_option = checklist_ontology_classification.get_child_by_title(
          title="Apple", type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title="Kiwi", type_=Option
      )
      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=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
      )

      label_row.add_classification_instance(checklist_classification_instance)


      label_row.save()

      ```

      ```python Example 2 theme={"dark"}
      #Import dependencies
      from __future__ import annotations
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import (
          Classification,
      )
      from collections import defaultdict
      from copy import deepcopy
      from dataclasses import dataclass, field
      from datetime import datetime
      from typing import (
          TYPE_CHECKING,
          Any,
          Dict,
          Iterable,
          List,
          Optional,
          Sequence,
          Set,
          Tuple,
          Union,
      )
      from dateutil.parser import parse
      from encord.constants.enums import DataType
      from encord.exceptions import LabelRowError
      from encord.objects import ChecklistAttribute, RadioAttribute, TextAttribute
      from encord.objects.answers import (
          Answer,
          _get_static_answer_map,
          get_default_answer_from_attribute,
      )

      from encord.objects.frames import (
          Frames,
          Range,
          Ranges,
      )
      from encord.objects.internal_helpers import (
          _infer_attribute_from_answer,
          _search_child_attributes,
      )
      from encord.objects.ontology_object import Object
      from encord.objects.options import Option
      from encord.objects.utils import check_email, short_uuid_str

      if TYPE_CHECKING:
          from encord.objects.ontology_labels_impl import LabelRowV2


      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"

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

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


      # Creating Checklist options- START
      # Specify the data unit to add classification
      label_row = project.list_label_rows_v2(
          data_title_eq="Blueberries_video.mp4"
      )[0]

      label_row.initialise_labels()


      # Assume that the following Checklist options exists in the ontology.

      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title="Many types of fruit?",
          type_=Classification,
      )

      apple_option = checklist_ontology_classification.get_child_by_title(
          title="Apple", type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title="Kiwi", type_=Option
      )

      checklist_classification_instance = (
          checklist_ontology_classification.create_instance()
      )

      checklist_classification_instance.set_answer(
          [apple_option, kiwi_option]
      )

      checklist_classification_instance.set_for_frames(
          frames=Range(start=193, end=197),
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
      )

      label_row.add_classification_instance(checklist_classification_instance)


      label_row.save()
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## Attributes

The following scripts assume that an object label called `Whale` has already been created. Each script retrieves the object instance and searches for the corresponding attribute within the Project's Ontology. For radio buttons and checklists, the scripts also identify the relevant attribute options.

* Replace `<private_key_path>` with the key to your private key for authentication.
* Replace `<project_hash>` with the hash of your Project.
* Replace `Whale` with the name of your object.
* Replace the attributes and attribute answers to suit your needs.

<CodeGroup>
  ```python Text theme={"dark"}
  # Import dependencies
  from typing import List

  from encord import EncordUserClient
  from encord.objects import LabelRowV2, OntologyStructure, Object, OntologyStructure

  # Instantiate Encord client by replacing <private_key_path> with the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

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

  # For simplicity, get only the first label row
  first_label_row: List[LabelRowV2] = project.list_label_rows_v2()[0]

  # Download the existing labels 
  first_label_row.initialise_labels()

  # Get the Ontology structure
  ontology_structure: OntologyStructure = first_label_row.ontology_structure

  #Assume that the following Object exists in the Ontology.
  object_label = ontology_structure.get_child_by_title(
      title="Whale",
      type_=Object
  )

  # Create object instance. We assume only 1 label
  object_instance = first_label_row.get_object_instances()[0]

  # Find the attribute name
  attribute = object_label.get_child_by_title("Description")

  # Set the answer for the attribute
  object_instance.set_answer(attribute=attribute, answer="This is a picture of a whale")

  # Save labels
  first_label_row.save()
  ```

  ```python Radio Button theme={"dark"}
  # Import dependencies
  from typing import List

  from encord import EncordUserClient
  from encord.objects import LabelRowV2, Option, Object, OntologyStructure

  # Instantiate Encord client by replacing <private_key_path> with the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

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

  # For simplicity, get only the first label row
  first_label_row: List[LabelRowV2] = project.list_label_rows_v2()[0]

  # Download the existing labels 
  first_label_row.initialise_labels()

  # Get the ontology structure
  ontology_structure: OntologyStructure = first_label_row.ontology_structure

  # Find Object label
  object_label = ontology_structure.get_child_by_title(
      title="Whale",
      type_=Object
  )

  # Create object instance. We assume only 1 label
  object_instance = first_label_row.get_object_instances()[0]

  # Find the attribute
  object_attribute = object_label.get_child_by_title("Colour")

  # Find the attribute option you want to set
  attribute_option = object_attribute.get_child_by_title(
      title="Purple",
      type_=Option
  )

  # Set the attribute option
  object_instance.set_answer(attribute_option)

  # Save labels
  first_label_row.save()
  ```

  ```python Checklist theme={"dark"}
  # Import dependencies
  from typing import List

  from encord import EncordUserClient
  from encord.objects import LabelRowV2, Option, Object, OntologyStructure

  # Instantiate Encord client by replacing <private_key_path> with the path to your private key
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path="<private_key_path>"
  )

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

  # For simplicity, get only the first label row
  first_label_row: List[LabelRowV2] = project.list_label_rows_v2()[0]

  # Download the existing labels 
  first_label_row.initialise_labels()

  # Get the Ontology structure
  ontology_structure: OntologyStructure = first_label_row.ontology_structure

  # Find Object label
  object_label = ontology_structure.get_child_by_title(
      title="Whale",
      type_=Object
  )

  # Create object instance. We assume only 1 label
  object_instance = first_label_row.get_object_instances()[0]

  # Find the attribute
  object_attribute = object_label.get_child_by_title("Characteristics")

  # Find the attribute option you want to set
  mammal_option = object_attribute.get_child_by_title(
      title="Mammal",
      type_=Option
  )

  # Find the attribute option you want to set
  big_option = object_attribute.get_child_by_title(
      title="Big",
      type_=Option
  )

  # Set the attribute options
  object_instance.set_answer([mammal_option, big_option])

  # Save labels
  first_label_row.save()
  ```
</CodeGroup>

### Nested Attributes

Radio button attributes can be nested. The following script assumes that an object label called `Whale` has already been created.

```python Nested Radio Attributes theme={"dark"}
# Import dependencies
from typing import List

from encord import EncordUserClient
from encord.objects import LabelRowV2, Option, Object, OntologyStructure

# Instantiate Encord client by replacing <private_key_path> with the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

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

# For simplicity, get only the first label row
first_label_row: List[LabelRowV2] = project.list_label_rows_v2()[0]

# Download the existing labels 
first_label_row.initialise_labels()

# Get the ontology structure
ontology_structure: OntologyStructure = first_label_row.ontology_structure

# Find Object label
object_label = ontology_structure.get_child_by_title(
    title="Whale",
    type_=Object
)

# Create object instance. We assume only 1 label
object_instance = first_label_row.get_object_instances()[0]

# Find the attribute
object_attribute = object_label.get_child_by_title("Colour")

# Find the attribute option you want to set
attribute_option = object_attribute.get_child_by_title(
    title="Blue",
    type_=Option
)

# Set the attribute option
object_instance.set_answer(attribute_option)

# Assume that the following Radio button options exists in the Ontology.
nested_radio_ontology_attribute: Classification = (
    ontology_structure.get_child_by_title(
        title="Any Other Colors?", type_=RadioAttribute
    )
)

# Assume the following radio button nested attribute exists in the Ontology
nested_radio_attribute_option = object_label.get_child_by_title(
    title="Pink",
    type_=Option
)

# Save labels
first_label_row.save()
```

***

### Relation Attributes

Relation attributes use text attributes as pointers to show a relationship between labels. When an attribute is marked as *Relation* the string `#relation` is appended to the attribute name.

You can specify relationships between any object labels in a data unit, if a Relation attribute is added to one object label type with Relation.

<Tip>Learn more about relation attributes in Encord [here](/platform-documentation/Annotate/annotate-ontologies/annotate-ontologies#relation-attributes).</Tip>

The following example uses bounding box and polygon object labels with a Text-Relation attribute and a Text attribute. The Text attribute can be used to provide more context for the relationship between object labels.

```python Relation Attributes expandable theme={"dark"}
from typing import List

from encord import EncordUserClient
from encord.objects import LabelRowV2, Object, OntologyStructure, ObjectInstance, TextAttribute
from encord.objects.coordinates import BoundingBoxCoordinates, PolygonCoordinates, PointCoordinate


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

# Ontology titles. Replace with your ontology titles
BB_OBJECT_TITLE = "Bounding Box"
PG_OBJECT_TITLE = "Polygon"
REL_ATTR_TITLE = "Relationship #relation"
SPECIFY_ATTR_TITLE = "Specify relationship"


# --- 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",
)

project = user_client.get_project(PROJECT_ID)


# Import labels to data units
data_unit_specs = {
    # -------- Image --------
    "cherries-015.jpg": {
        0: {
            "bb": BoundingBoxCoordinates(height=0.30, width=0.30, top_left_x=0.05, top_left_y=0.05),
            "pg": PolygonCoordinates(
                polygons=[
                    [
                        [
                            PointCoordinate(x=0.40, y=0.40),
                            PointCoordinate(x=0.60, y=0.40),
                            PointCoordinate(x=0.50, y=0.60),
                        ]
                    ]
                ]
            ),
            "bb_specify_text": "BB references the Polygon",
            "pg_specify_text": "Polygon is referenced by the BB",
        }
    },

    # -------- Video 1 --------
    "cherries-vid-002.mp4": {
        12: {
            "bb": BoundingBoxCoordinates(height=0.25, width=0.25, top_left_x=0.10, top_left_y=0.10),
            "pg": PolygonCoordinates(
                polygons=[
                    [
                        [
                            PointCoordinate(x=0.55, y=0.55),
                            PointCoordinate(x=0.75, y=0.55),
                            PointCoordinate(x=0.65, y=0.75),
                        ]
                    ]
                ]
            ),
            "bb_specify_text": "BB references PG (video-001)",
            "pg_specify_text": "PG references BB (video-001)",
        },
        15: {
            "bb": BoundingBoxCoordinates(height=0.27, width=0.27, top_left_x=0.12, top_left_y=0.12),
            "pg": PolygonCoordinates(
                polygons=[
                    [
                        [
                            PointCoordinate(x=0.57, y=0.57),
                            PointCoordinate(x=0.77, y=0.57),
                            PointCoordinate(x=0.67, y=0.77),
                        ]
                    ]
                ]
            ),
        },
    },

    # -------- Video 2 --------
    "blueberry-02.mp4": {
        101: {
            "bb": BoundingBoxCoordinates(height=0.20, width=0.20, top_left_x=0.00, top_left_y=0.00),
            "pg": PolygonCoordinates(
                polygons=[
                    [
                        [
                            PointCoordinate(x=0.30, y=0.30),
                            PointCoordinate(x=0.50, y=0.30),
                            PointCoordinate(x=0.40, y=0.50),
                        ]
                    ]
                ]
            ),
            "bb_specify_text": "BB references PG (video-002)",
            "pg_specify_text": "PG references BB (video-002)",
        }
    },
}


# Process each data unit
for data_title, frame_map in data_unit_specs.items():
    print(f"\nProcessing {data_title}")

    # Get label row for this data unit
    label_rows: List[LabelRowV2] = project.list_label_rows_v2(data_title_eq=data_title)
    if not label_rows:
        print(f"Skipping {data_title}: no label row found")
        continue

    label_row: LabelRowV2 = label_rows[0]

    # Initialise labels
    label_row.initialise_labels()

    # Get ontology FROM label row
    ontology_structure: OntologyStructure = label_row.ontology_structure
    assert ontology_structure is not None, "Ontology not available after initialise_labels()"

    # Find ontology objects
    bb_object_label: Object = ontology_structure.get_child_by_title(title=BB_OBJECT_TITLE, type_=Object)
    pg_object_label: Object = ontology_structure.get_child_by_title(title=PG_OBJECT_TITLE, type_=Object)

    assert bb_object_label is not None, f"Object {BB_OBJECT_TITLE!r} not found in ontology."
    assert pg_object_label is not None, f"Object {PG_OBJECT_TITLE!r} not found in ontology."

    # Find attributes ON EACH object
    bb_relation_attr: TextAttribute = bb_object_label.get_child_by_title(type_=TextAttribute, title=REL_ATTR_TITLE)
    bb_specify_attr: TextAttribute = bb_object_label.get_child_by_title(type_=TextAttribute, title=SPECIFY_ATTR_TITLE)

    pg_relation_attr: TextAttribute = pg_object_label.get_child_by_title(type_=TextAttribute, title=REL_ATTR_TITLE)
    pg_specify_attr: TextAttribute = pg_object_label.get_child_by_title(type_=TextAttribute, title=SPECIFY_ATTR_TITLE)

    assert bb_relation_attr is not None, f"{REL_ATTR_TITLE!r} not found on {BB_OBJECT_TITLE!r}"
    assert bb_specify_attr is not None, f"{SPECIFY_ATTR_TITLE!r} not found on {BB_OBJECT_TITLE!r}"
    assert pg_relation_attr is not None, f"{REL_ATTR_TITLE!r} not found on {PG_OBJECT_TITLE!r}"
    assert pg_specify_attr is not None, f"{SPECIFY_ATTR_TITLE!r} not found on {PG_OBJECT_TITLE!r}"

    # Create labels
    bb_instance: ObjectInstance = bb_object_label.create_instance()
    pg_instance: ObjectInstance = pg_object_label.create_instance()

    bb_specify_text_to_set = None
    pg_specify_text_to_set = None

    # Assign coordinates per frame
    for frame_number, coords in frame_map.items():
        bb_instance.set_for_frames(coordinates=coords["bb"], frames=frame_number)
        pg_instance.set_for_frames(coordinates=coords["pg"], frames=frame_number)

        # set specify text once
        if bb_specify_text_to_set is None:
            bb_specify_text_to_set = coords.get("bb_specify_text")
        if pg_specify_text_to_set is None:
            pg_specify_text_to_set = coords.get("pg_specify_text")

    # Add instances to the label row
    label_row.add_object_instance(pg_instance)
    label_row.add_object_instance(bb_instance)

    # Relations
    bb_instance.set_answer(attribute=bb_relation_attr, answer=pg_instance.object_hash)
    pg_instance.set_answer(attribute=pg_relation_attr, answer=bb_instance.object_hash)

    # Human-readable relationship text
    if isinstance(bb_specify_text_to_set, str) and bb_specify_text_to_set:
        bb_instance.set_answer(attribute=bb_specify_attr, answer=bb_specify_text_to_set)

    if isinstance(pg_specify_text_to_set, str) and pg_specify_text_to_set:
        pg_instance.set_answer(attribute=pg_specify_attr, answer=pg_specify_text_to_set)

    # Save labels
    label_row.save()
    print(f"Saved labels for {data_title}")

print("\nDone: Bounding Box ↔ Polygon relations added for image + video data units.")

```

### Dynamic Attributes

Dynamic attributes are attributes for object instances where the answer can change in each frame. You can read more about them [here](/platform-documentation/Annotate/annotate-label-editor/annotate-videos#dynamic-attributes).

The following example adds bounding boxes for the label `Person` to three frames. It then sets the dynamic attribute `Position` to `Walking` and `Standing`. Wherever you can set frames, you can either set a single integer, a Range, or a list of Ranges.

```python theme={"dark"}
# Import dependencies
from typing import List

from encord import EncordUserClient
from encord.objects import LabelRowV2, Object, ObjectInstance, OntologyStructure
from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

# Instantiate Encord client by replacing <private_key_path> with the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

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

# For simplicity, get only the first label row
first_label_row: LabelRowV2 = project.list_label_rows_v2()[0]

# Download the existing labels
first_label_row.initialise_labels()

# Find the object in the Ontology
person_ontology_object: Object = ontology_structure.get_child_by_title(
    "Person", type_=Object
)

# Find the dynamic attribute in the Ontology
position_attribute = person_ontology_object.get_child_by_title(
    title="Position",  # The options here are "Standing" or "Walking"
    type_=RadioAttribute,
)

# Coordinates for bounding boxes on frames 3, 4, and 5
coordinates_per_frame = {
    3: BoundingBoxCoordinates(
        height=0.5,
        width=0.5,
        top_left_x=0.2,
        top_left_y=0.2,
    ),
    4: BoundingBoxCoordinates(
        height=0.5,
        width=0.5,
        top_left_x=0.3,
        top_left_y=0.3,
    ),
    5: BoundingBoxCoordinates(
        height=0.5,
        width=0.5,
        top_left_x=0.4,
        top_left_y=0.4,
    ),
}

# Add the bounding box labels to the object instance for each frame
for frame_number, coordinates in coordinates_per_frame.items():
    box_object_instance.set_for_frames(
        coordinates=coordinates, frames=frame_number
    )

# Link the object instance to the label row
first_label_row.add_object_instance(box_object_instance)

# Assume the person is standing in frame 1
person_object_instance.set_answer(
    answer=position_attribute.get_child_by_title("Standing", type_=Option),
    frames=0,
)

# Assume the person is walking in frames 2 and 3
person_object_instance.set_answer(
    answer=position_attribute.get_child_by_title("Walking", type_=Option),
    frames=Range(start=1, end=3),
)

# Save labels
first_label_row.save()
```

## Import Labels in Bulk

When importing a large number of labels, here are some tips to improve your label import performance:

* A data unit is one image, one image group, one image sequence, one video, or one DICOM series. One data unit is equivalent to one label row. You only need to call the [initialise\_labels](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects#initialise-labels) function and save the label row ONCE per data unit. It does not matter how many labels are added to the data unit between the `initialise_labels` function and saving the label row.

* Use the [bundle](/sdk-documentation/sdk-references/http.bundle#bundle) function to significantly improve the import performance when you do any of the following:
  * Import labels on a large number of individual images (NOT image groups, image sequences, videos, or DICOM sets).
  * Import labels on a large number of data units at once.

<Warning>
  In the following code, ensure you replace:

  * `<private_key_path>` with the full path to your private key.
  * `<project-id>` with the unique ID of your Project.
  * `#Perform label row operation before in this loop` with the label row operations you want to perform.
  * Optionally, change the value of `BUNDLE_SIZE` to suit your needs. We strongly recommend NOT bundling more than 1000 operations at once, because bundling more than 1000 operations can reduce performance instead of improving performance.
</Warning>

<CodeGroup>
  ```python Bundle template for label import theme={"dark"}

  # Import dependencies
  from pathlib import Path

  from encord import EncordUserClient, Project
  from encord.objects import (
      Object,
      ObjectInstance,
      OntologyStructure,
  )
  from encord.objects.coordinates import BoundingBoxCoordinates

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

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

  # Gets Project to export labels
  project: Project = user_client.get_project(PROJECT_HASH)

  label_rows = project.list_label_rows_v2()
  BUNDLE_SIZE = 100

  # Initialize label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  for label_row in label_rows:

      # Write any label row operation here. For example import, or export label rows. 


  # Saving changes to label rows using bundles
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.save(bundle=bundle) 
  ```
</CodeGroup>


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



## Overview

To upload labels to a Consensus Project, you need to create a Consensus branch.

ALL Consensus branches start with `encord-`.

## Supported Label/Annotation Formats

**[Encord Format (Recommended)](#import-encord-format-labels)**

* Supports multi-level nested classifications (radio, checklist, or free-form text) under objects or classifications.
* Handles all object types and classification.

**[COCO Format](#import-coco-labels-to-consensus-branches)**

Does not support multiple levels of nested classifications (radio, checklist, or free-form text) under tools or classifications.

### Confidence Score

You can include confidence scores when uploading labels/annotations. Encord automatically calculates model metrics based on your label and prediction sets and assigned confidence scores.

## Label Branches

When importing label/annotation sets into a Consensus Project, they are added as branches to individual label rows on your data units (images, videos, audio). Each data unit has the following:

* A MAIN branch for ground truth annotations or pre-labels.
* Optional Consensus branches and Prediction branches for different label/annotation or prediction sets.

![Label branches](https://storage.googleapis.com/docs-media.encord.com/static/img/annotate/consensus-branch.png)

<Tip>You can [export main branch labels from the UI](/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels). [Consensus labels and model predictions can only be exported using the SDK](/sdk-documentation/sdk-labels/sdk-export#export-all-consensus-labels).</Tip>

## Import Labels/Annotations to Consensus Projects

Import your labels to a Project in Annotate. Encord currently supports importing labels from the Encord format and from COCO.

### Import Encord-Format Labels

Use `branch_name` to create a label branch in `label_rows_v2` for a data unit.

Use `branch_name` to create a label branch in `label_rows_v2` for a data unit.

<Warning>
  * `branch_name` supports alphanumeric characters (a-z, A-Z, 0-9) and is case sensitive
  * `branch_name` supports the following special characters: hyphens (-), underscores (\_), and periods (.)
</Warning>

<AccordionGroup>
  <Accordion title="Bounding Box">
    **Example 1**

    Imports a single bounding box (`Cherry`) to a single image (`cherry_001.png`).

    **Example 2:**

    Imports three instances (tracking an object across three sequential frames: 103, 104, and 105) of a bounding box (`Cherry`) to a video (`Cherries_video.mp4`).

    **Example 3**

    Imports three bounding boxes (`Cherry`) to a single image (`cherry_001.png`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 103, 104, 105, object 2 - frames 206, 207, 208, and object 3 - frames 313, 315, 317) of three bounding boxes (`Cherry`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Bounding Box Template theme={"dark"}
      # 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

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"
      PROJECT_ID = "<unique-id-of-your-project>"
      CONSENSUS_BRANCH_NAME = "<name-of-your-label-branch>"
      ONTOLOGY_OBJECT_TITLE = "<name-of-ontology-object>" # Name of object label in your Ontology
      DATA_UNIT_TITLES = ["<data-unit-title-1>", "<data-unit-title-2>"]  # List of specific data units

      # Ensure SSH path and project id are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_ID, "Project id cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the label branch
      project = user_client.get_project(PROJECT_ID)
      all_consensus_branch_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      consensus_branch_rows = [
          row for row in all_consensus_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not consensus_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in consensus_branch_rows])

      # Retrieve the specified ontology object by title
      ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      # Initialize labels for each selected label row in the label branch
      with project.create_bundle() as bundle:
          for row in consensus_branch_rows:
              row.initialise_labels(bundle=bundle)

      # Add bounding box labels to each filtered label row
      for row in consensus_branch_rows:
          # Instantiate an object instance for bounding box labels
          inst = ontology_object.create_instance()
          inst.set_for_frames(
              coordinates=BoundingBoxCoordinates(
                  height=0.1,
                  width=0.1,
                  top_left_x=0.5,
                  top_left_y=0.5,
              ),
              frames=0,  # Apply to the specified frame
              manual_annotation=False,  # Set to False as this is a label
              confidence=1, # Confidence of your label
          )

          # Add the label instance to the label row
          row.add_object_instance(inst)

      with project.create_bundle() as bundle:
          # Save the row with labels within the bundle
          for row in consensus_branch_rows:
              row.save(bundle=bundle)
      ```

      ```python Example 1 theme={"dark"}
      # 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

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "80ae53e3-594c-4120-a108-ee4af105bff3"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"
      ONTOLOGY_OBJECT_TITLE = "Cherry" # Name of object label in your Ontology
      DATA_UNIT_TITLES = ["cherry_001.png"]  # List of specific data units

      # Ensure SSH path and project id are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_ID, "Project id cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the label branch
      project = user_client.get_project(PROJECT_ID)
      all_consensus_branch_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      consensus_branch_rows = [
          row for row in all_consensus_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not consensus_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in consensus_branch_rows])

      # Retrieve the specified ontology object by title
      ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      # Initialize labels for each selected label row in the label branch
      with project.create_bundle() as bundle:
          for row in consensus_branch_rows:
              row.initialise_labels(bundle=bundle)

      # Add bounding box labels to each filtered label row
      for row in consensus_branch_rows:
          # Instantiate an object instance for bounding box labels
          inst = ontology_object.create_instance()
          inst.set_for_frames(
              coordinates=BoundingBoxCoordinates(
                  height=0.1,
                  width=0.1,
                  top_left_x=0.5,
                  top_left_y=0.5,
              ),
              frames=0,  # Apply to the specified frame
              manual_annotation=False,  # Set to False as this is a label
              confidence=1, # Confidence of your label
          )

          # Add the label instance to the label row
          row.add_object_instance(inst)

      with project.create_bundle() as bundle:
          for row in consensus_branch_rows:
              # Save the row with labels within the bundle
              row.save(bundle=bundle)
      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"
      ONTOLOGY_OBJECT_TITLE = "Cherry"
      DATA_UNIT_TITLES = ["Cherries_video.mp4"]  # List of specific video data units

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the label branch
      project = user_client.get_project(PROJECT_ID)
      all_consensus_branch_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      consensus_branch_rows = [
          row for row in all_consensus_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not consensus_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in consensus_branch_rows])

      # Retrieve the specified ontology object by title
      box_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      with project.create_bundle() as bundle:
          # Initialize labels for each selected label row in the label branch
          for label_row in consensus_branch_rows:
              label_row.initialise_labels(bundle=bundle)

      # Define frame coordinates for video tracking
      coordinates_per_frame = {
          103: BoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
          ),
          104: BoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
          ),
          105: BoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
          ),
      }

      # Add bounding box labels to each filtered label row across specified frames
      for label_row in consensus_branch_rows:
          # Instantiate an object instance for bounding box labels
          box_object_instance = box_ontology_object.create_instance()
          
          # Apply bounding box coordinates for each specified frame
          for frame_number, coordinates in coordinates_per_frame.items():
              box_object_instance.set_for_frames(
                  coordinates=coordinates, 
                  frames=frame_number,  # Specify the frame number
                  manual_annotation=False  # Mark as a label
              )
          
          # Add the object instance to the label row
          label_row.add_object_instance(box_object_instance)
          
      with project.create_bundle() as bundle:
          for label_row in consensus_branch_rows:
              # Save the label row with the updated labels within the bundle
              label_row.save(bundle=bundle)
      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-II"
      ONTOLOGY_OBJECT_TITLE = "Cherry"
      DATA_UNIT_TITLES = ["cherry_001.png"]  # List of specific image data units

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the label branch
      project = user_client.get_project(PROJECT_ID)
      all_consensus_branch_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      consensus_branch_rows = [
          row for row in all_consensus_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not consensus_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in consensus_branch_rows])

      # Retrieve the specified ontology object by title
      box_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      with project.create_bundle() as bundle:
          # Initialize labels for each selected label row in the label branch
          for label_row in consensus_branch_rows:
              label_row.initialise_labels(bundle=bundle)

      # Add bounding box labels to each filtered label row
      for label_row in consensus_branch_rows:
          # Define bounding box coordinates for each label
          bounding_boxes = [
              BoundingBoxCoordinates(height=0.1, width=0.1, top_left_x=0.2, top_left_y=0.2),
              BoundingBoxCoordinates(height=0.1, width=0.1, top_left_x=0.3, top_left_y=0.3),
              BoundingBoxCoordinates(height=0.1, width=0.1, top_left_x=0.4, top_left_y=0.4),
          ]

          # Instantiate and set labels for each bounding box
          for coordinates in bounding_boxes:
              box_object_instance = box_ontology_object.create_instance()
              box_object_instance.set_for_frames(
                  coordinates=coordinates,
                  frames=0,  # Image frame
                  manual_annotation=False,  # Mark as label
                  confidence=1.0,
              )

              # Add each object instance to the label row
              label_row.add_object_instance(box_object_instance)
          
      with project.create_bundle() as bundle:
          for label_row in consensus_branch_rows:
              # Save the label row with the updated labels within the bundle
              label_row.save(bundle=bundle)
      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-II"
      ONTOLOGY_OBJECT_TITLE = "Cherry"
      DATA_UNIT_TITLES = ["Cherries_video.mp4"]  # List of specific video data units

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the label branch
      project = user_client.get_project(PROJECT_ID)
      all_consensus_branch_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      consensus_branch_rows = [
          row for row in all_consensus_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not consensus_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in consensus_branch_rows])

      # Retrieve the specified ontology object by title
      box_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      with project.create_bundle() as bundle:
          # Initialize labels for each selected label row in the label branch
          for label_row in consensus_branch_rows:
              label_row.initialise_labels(bundle=bundle)

      # Define frame coordinates for tracking across multiple frames for each object
      tracking_coordinates = [
          {  # First object tracked across frames 103, 104, 105
              103: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.2, top_left_y=0.2),
              104: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.3, top_left_y=0.3),
              105: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.4, top_left_y=0.4)
          },
          {  # Second object tracked across frames 206, 207, 208
              206: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.2, top_left_y=0.2),
              207: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.3, top_left_y=0.3),
              208: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.4, top_left_y=0.4)
          },
          {  # Third object tracked across frames 313, 315, 317
              313: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.2, top_left_y=0.2),
              315: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.3, top_left_y=0.3),
              317: BoundingBoxCoordinates(height=0.5, width=0.5, top_left_x=0.4, top_left_y=0.4)
          },
      ]

      # Add bounding box labels to each filtered label row across specified frames
      for label_row in consensus_branch_rows:
          for frame_coordinates in tracking_coordinates:
              box_object_instance = box_ontology_object.create_instance()
              
              for frame_number, coordinates in frame_coordinates.items():
                  box_object_instance.set_for_frames(
                      coordinates=coordinates, 
                      frames=frame_number,
                      manual_annotation=False,  # Mark as a label
                      confidence=1.0
                  )
              
              # Add each object instance to the label row
              label_row.add_object_instance(box_object_instance)
          
      with project.create_bundle() as bundle:
          for label_row in consensus_branch_rows:
              # Save the label row with the updated labels within the bundle
              label_row.save(bundle=bundle)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Rotatable Bounding Box">
    **Example 1**

    Imports a single rotatable bounding box (`Other type of fruit`) to a single image (`apple_001.png`).

    **Example 2**

    Imports three instances (tracking an object across three sequential frames: 120, 121, and 122) of a bounding box (`Other type of fruit`) to a video (`Cherries_video.mp4`).

    **Example 3**

    Imports three rotatable bounding boxes (`Other type of fruit`) to a single image (`apple_001.png`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 120, 121, 122, object 2 - frames 222, 224, 226, and object 3 - frames 321, 323, 325) of three rotatable bounding boxes (`Other type of fruit`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Import Rotatable Bounding Box Template theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"
      PROJECT_ID = "<unique-id-for-project>"
      CONSENSUS_BRANCH_NAME = "<name-of-your-label-branch>"
      ONTOLOGY_OBJECT_TITLE = "<rotatable-bounding-box-class-title>"
      DATA_UNIT_TITLES = ["<data-unit-title-1>", "<data-unit-title-2>"]  # Specify the data unit titles here

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the label branch
      project = user_client.get_project(PROJECT_ID)
      all_consensus_branch_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on the specified data unit titles
      consensus_branch_rows = [
          row for row in all_consensus_branch_rows 
          if row.data_title in DATA_UNIT_TITLES
      ]

      if not consensus_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in consensus_branch_rows])

      # Retrieve the specified ontology object by title
      rbb_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      with project.create_bundle() as bundle:
          # Initialize labels for each selected label row in the label branch
          for label_row in consensus_branch_rows:
              label_row.initialise_labels(bundle=bundle)

      # Define rotatable bounding box coordinates and frame for each object
      rotatable_bounding_box_labels = [
          {
              "frame_number": 0,
              "coordinates": RotatableBoundingBoxCoordinates(
                  height=0.3,
                  width=0.2,
                  top_left_x=0.1,
                  top_left_y=0.1,
                  theta=15  # Angle of rotation in degrees
              ),
          },
          {
              "frame_number": 5,
              "coordinates": RotatableBoundingBoxCoordinates(
                  height=0.25,
                  width=0.25,
                  top_left_x=0.15,
                  top_left_y=0.15,
                  theta=30
              ),
          },
          {
              "frame_number": 10,
              "coordinates": RotatableBoundingBoxCoordinates(
                  height=0.2,
                  width=0.3,
                  top_left_x=0.2,
                  top_left_y=0.2,
                  theta=45
              ),
          },
      ]

      # Add rotatable bounding box labels to each filtered label row
      for label_row in consensus_branch_rows:
          for label in rotatable_bounding_box_labels:
              rbb_object_instance = rbb_ontology_object.create_instance()
              
              rbb_object_instance.set_for_frames(
                  coordinates=label["coordinates"],
                  frames=label["frame_number"],
                  manual_annotation=False,  # Mark as a label
                  confidence=1.0
              )
              
              # Link the object instance to the label row
              label_row.add_object_instance(rbb_object_instance)
          
      with project.create_bundle() as bundle:
          for label_row in consensus_branch_rows:
              # Save the label row with the updated labels within the bundle
              label_row.save(bundle=bundle)
      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"
      DATA_UNIT_TITLE = "apple_001.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Other type of fruit"  # Ontology class title for rotatable bounding box

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          ssh_private_key_path=Path(SSH_PATH).read_text()
      )

      # Get the project and list label rows for the label branch
      project = user_client.get_project(PROJECT_ID)
      consensus_branch_rows = project.list_label_rows_v2(
          branch_name=CONSENSUS_BRANCH_NAME,
          data_title_eq=DATA_UNIT_TITLE
      )

      if not consensus_branch_rows:
          print("No matching data unit found in the specified branch.")
      else:
          print("Data unit found:", consensus_branch_rows[0].data_title)

      # Retrieve the specified ontology object by title
      rbb_ontology_object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Object
      )

      # Prepare for label imports by creating a bundle
      with project.create_bundle() as bundle:
          # Initialize labels for the label row in the label branch
          label_row = consensus_branch_rows[0]
          label_row.initialise_labels(bundle=bundle)

      # Define the rotatable bounding box coordinates for label
      rbb_coordinates = RotatableBoundingBoxCoordinates(
          height=0.23,
          width=0.13,
          top_left_x=0.3,
          top_left_y=0.5,
          theta=95  # Angle of rotation in degrees
      )

      # Add rotatable bounding box label to the label row
      rbb_object_instance = rbb_ontology_object.create_instance()
      rbb_object_instance.set_for_frames(
          coordinates=rbb_coordinates,
          frames=0,  # Frame for the image
          manual_annotation=False,  # Mark as a label
          confidence=1.0
      )

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

      with project.create_bundle() as bundle:
          # Save the label row with the updated labels within the bundle
          # (useful if you're calling `initialise_labels` on many label rows
          label_row.save(bundle=bundle)
      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify the label branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # The title of the video data unit
      ONTOLOGY_OBJECT_TITLE = "Other type of fruit"  # The ontology object title for the bounding box

      # 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)

      # Creating multiple instances of a rotatable bounding box - START
      label_row = project.list_label_rows_v2(
          branch_name=CONSENSUS_BRANCH_NAME,  # Use the label branch
          data_title_eq=DATA_UNIT_TITLE
      )[0]


      with project.create_bundle() as bundle:
          # Initialize labels for the selected label row in the label branch
          label_row.initialise_labels(bundle=bundle)

      # Find a rotatable bounding box annotation object in the project ontology
      rbb_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Define the coordinates for the rotatable bounding boxes across frames
      coordinates_per_frame = {
          120: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
              theta=23
          ),
          121: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
              theta=27
          ),
          122: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
              theta=57
          ),
      }

      # Iterate through the frames and create instances for each bounding box
      for frame_number, coordinates in coordinates_per_frame.items():
          # Instantiate an object instance from the ontology node for each frame
          rbb_object_instance: ObjectInstance = rbb_ontology_object.create_instance()

          # Set the coordinates for the rotatable bounding box for this frame
          rbb_object_instance.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=False,  # Mark as a label
              confidence=1.0  # Optional confidence score
          )

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

      with project.create_bundle() as bundle:
          # Save the label row with the updated labels within the bundle
          label_row.save(bundle=bundle)
      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-II"  # Specify the label branch
      DATA_UNIT_TITLE = "apple_001.jpg"  # The title of the image data unit
      ONTOLOGY_OBJECT_TITLE = "Other type of fruit"  # The ontology object title for the bounding box

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

      # Get the project and list label rows for the label branch
      project: Project = user_client.get_project(PROJECT_ID)
      label_row = project.list_label_rows_v2(
          branch_name=CONSENSUS_BRANCH_NAME,  # Use the label branch
          data_title_eq=DATA_UNIT_TITLE
      )[0]

      with project.create_bundle() as bundle:
          # Initialize labels for the selected label row in the label branch
          label_row.initialise_labels(bundle=bundle)

      # Find the rotatable bounding box annotation object in the project ontology
      rbb_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Define rotatable bounding box instances with different coordinates
      rotatable_bounding_boxes = [
          RotatableBoundingBoxCoordinates(
              height=0.23,
              width=0.13,
              top_left_x=0.1,
              top_left_y=0.2,
              theta=37
          ),
          RotatableBoundingBoxCoordinates(
              height=0.23,
              width=0.13,
              top_left_x=0.3,
              top_left_y=0.5,
              theta=95
          ),
          RotatableBoundingBoxCoordinates(
              height=0.23,
              width=0.13,
              top_left_x=0.4,
              top_left_y=0.6,
              theta=70
          ),
      ]

      # Iterate over each bounding box and apply them as labels to the label row
      for rbb_coordinates in rotatable_bounding_boxes:
          rbb_object_instance: ObjectInstance = rbb_ontology_object.create_instance()

          rbb_object_instance.set_for_frames(
              coordinates=rbb_coordinates,
              frames=0,  # Image frame
              manual_annotation=False,  # Mark as a label
              confidence=1.0
          )

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

      with project.create_bundle() as bundle:
          # Save the label row with the updated labels within the bundle
          label_row.save(bundle=bundle)
      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import RotatableBoundingBoxCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "<name-of-your-label-branch>"  # Specify the label branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # The title of the video data unit
      ONTOLOGY_OBJECT_TITLE = "Other type of fruit"  # The ontology object title for the bounding box

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

      # Get the project and list label rows for the label branch
      project: Project = user_client.get_project(PROJECT_ID)
      label_row = project.list_label_rows_v2(
          branch_name=CONSENSUS_BRANCH_NAME,  # Use the label branch
          data_title_eq=DATA_UNIT_TITLE
      )[0]

      with project.create_bundle() as bundle:
          # Initialize labels for the selected label row in the label branch
          label_row.initialise_labels(bundle=bundle)

      # Find the rotatable bounding box annotation object in the project ontology
      rbb_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Define frame coordinates for the first rotatable bounding box
      coordinates_per_frame_01 = {
          120: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
              theta=23
          ),
          121: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
              theta=27
          ),
          122: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
              theta=57
          ),
      }

      # Create and link the first rotatable bounding box to the label row
      rbb_object_instance_01: ObjectInstance = rbb_ontology_object.create_instance()
      for frame_number, coordinates in coordinates_per_frame_01.items():
          rbb_object_instance_01.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=False,  # Mark as a label
              confidence=1.0  # Optional confidence score
          )
      label_row.add_object_instance(rbb_object_instance_01)

      # Define frame coordinates for the second rotatable bounding box
      coordinates_per_frame_02 = {
          222: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
              theta=23
          ),
          224: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
              theta=27
          ),
          226: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
              theta=57
          ),
      }

      # Create and link the second rotatable bounding box to the label row
      rbb_object_instance_02: ObjectInstance = rbb_ontology_object.create_instance()
      for frame_number, coordinates in coordinates_per_frame_02.items():
          rbb_object_instance_02.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=False,  # Mark as a label
              confidence=1.0  # Optional confidence score
          )
      label_row.add_object_instance(rbb_object_instance_02)

      # Define frame coordinates for the third rotatable bounding box
      coordinates_per_frame_03 = {
          321: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.2,
              top_left_y=0.2,
              theta=23
          ),
          323: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.3,
              top_left_y=0.3,
              theta=27
          ),
          325: RotatableBoundingBoxCoordinates(
              height=0.5,
              width=0.5,
              top_left_x=0.4,
              top_left_y=0.4,
              theta=57
          ),
      }

      # Create and link the third rotatable bounding box to the label row
      rbb_object_instance_03: ObjectInstance = rbb_ontology_object.create_instance()
      for frame_number, coordinates in coordinates_per_frame_03.items():
          rbb_object_instance_03.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=False,  # Mark as a label
              confidence=1.0  # Optional confidence score
          )
      label_row.add_object_instance(rbb_object_instance_03)

      with project.create_bundle() as bundle:
          # Save the label row with the updated labels within the bundle
          label_row.save(bundle=bundle)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Polygons (Advanced)">
    Polygons can have simple and complex shapes, including being enclosed in one another, and encompassing separate regions. In each case the polygon's coordinates are arranged in a different way.

    Specifying coordinates for polygons uses this format:

    <CodeGroup>
      ```python Simple theme={"dark"}

      PolygonCoordinates(polygons=[[[PointCoordinate(x1, y1), PointCoordinate(x2, y2),...]]]

      ```

      ```python Donut theme={"dark"}

      PolygonCoordinates(polygons=
      [
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Outer ring
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Inner ring
          ]
      ]

      ```

      ```python Multiple Polygons theme={"dark"}

      PolygonCoordinates(polygons=
      [
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 1
          ],
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 2
          ],
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 3
          ],

      ]

      ```

      ```python Donut with Object Inside theme={"dark"}

      PolygonCoordinates(polygons=
      [
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Outer ring
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Inner ring
          ],
          [
              [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon inside
          ],

      ]

      ```
    </CodeGroup>

    **Simple Polygon**

    Import a simple polygon using the recommended method.

    <div>
      <img />
    </div>

    **Donut**

    Import a complex polygon with a hole in it.

    <div>
      <img />
    </div>

    **Multiple Polygons**

    Import a complex polygon that is in multiple parts.

    <div>
      <img />
    </div>

    **Donut with Object Inside**

    Imports a complex polygon that has a hole in it with another polygon inside.

    <div>
      <img />
    </div>

    <CodeGroup title="Complex Polygons">
      ```python Simple Polygon theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

      # Define coordinates for each image
      image_annotations = {
          "cherry-002-dup-001.jpg": [
              [  # Simple Polygon
                  [PointCoordinate(1.000, 0.500), PointCoordinate(0.750, 0.933), 
                   PointCoordinate(0.250, 0.933), PointCoordinate(0.000, 0.500), 
                   PointCoordinate(0.250, 0.067), PointCoordinate(0.750, 0.067)]
              ]
          ],
          
          "cherry-002-dup-002.jpg": [
              [  # Simple Polygon
                  [PointCoordinate(0.900, 0.400), PointCoordinate(0.700, 0.850), 
                   PointCoordinate(0.300, 0.850), PointCoordinate(0.100, 0.400), 
                   PointCoordinate(0.300, 0.100), PointCoordinate(0.700, 0.100)]
              ]
          ],
      }

      # Ensure SSH path and project id are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_ID, "Project id cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      # Get project and list label rows for the specified branch
      project = user_client.get_project(PROJECT_ID)
      all_label_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on images in `image_annotations`
      label_rows = [row for row in all_label_rows if row.data_title in image_annotations]

      if not label_rows:
          print("No matching label rows found for specified images in branch '{CONSENSUS_BRANCH_NAME}'.")
          exit()

      print("Processing label rows for:", [row.data_title for row in label_rows])

      with project.create_bundle() as bundle:
          # Prepare for labeling
          for label_row in label_rows:
              label_row.initialise_labels(bundle=bundle)

      for label_row in label_rows:
          image_title = label_row.data_title  # Get the image title
          polygon_data = image_annotations.get(image_title, [])  # Get associated polygons

          if not polygon_data:
              print(f"No polygon data found for {image_title}, skipping.")
              continue

          # Retrieve the specified ontology object by title
          polygon_ontology_object = project.ontology_structure.get_child_by_title(
              title=ONTOLOGY_OBJECT_TITLE,
              type_=Object
          )

          # Iterate through each polygon in the image's annotation data
          for polygon in polygon_data:
              # Instantiate an object instance from the polygon ontology node
              polygon_object_instance = polygon_ontology_object.create_instance()

              # Set the coordinates for the polygon
              polygon_object_instance.set_for_frames(
                  coordinates=PolygonCoordinates(polygon),
                  frames=0,  # Apply to the specified frame
                  manual_annotation=True,  # Set to True for manual annotation
                  confidence=1.0,  # Confidence of your label
              )

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

      with project.create_bundle() as bundle:
          for label_row in label_rows:
              # Save the label row with the polygon object instance within the bundle
              label_row.save(bundle=bundle)

      print("Label rows updated with polygon instances.")

      ```

      ```python Donut theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

      # Define coordinates for each image (supporting both outer and inner rings)
      image_annotations = {
          "cherry-002-dup-004.jpg": [
              # Outer ring
              [
                  [PointCoordinate(1.000, 0.500), PointCoordinate(0.750, 0.933), 
                   PointCoordinate(0.250, 0.933), PointCoordinate(0.000, 0.500), 
                   PointCoordinate(0.250, 0.067), PointCoordinate(0.750, 0.067)],
              ],
              # Inner ring (hole)
              [
                  [PointCoordinate(0.750, 0.500), PointCoordinate(0.625, 0.717), 
                   PointCoordinate(0.375, 0.717), PointCoordinate(0.250, 0.500), 
                   PointCoordinate(0.375, 0.284), PointCoordinate(0.625, 0.284)]
              ]
          ],
          
          "cherry-002-dup-003.jpg": [
              # Outer ring
              [
                  [PointCoordinate(0.900, 0.400), PointCoordinate(0.700, 0.850), 
                   PointCoordinate(0.300, 0.850), PointCoordinate(0.100, 0.400), 
                   PointCoordinate(0.300, 0.100), PointCoordinate(0.700, 0.100)],
              ],
              # Inner ring (hole)
              [
                  [PointCoordinate(0.700, 0.400), PointCoordinate(0.600, 0.650), 
                   PointCoordinate(0.400, 0.650), PointCoordinate(0.300, 0.400), 
                   PointCoordinate(0.400, 0.200), PointCoordinate(0.600, 0.200)]
              ]
          ],
      }

      # Ensure SSH path and project id are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_ID, "Project id cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      # Get project and list label rows for the specified branch
      project = user_client.get_project(PROJECT_ID)
      all_label_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on images in `image_annotations`
      label_rows = [row for row in all_label_rows if row.data_title in image_annotations]

      if not label_rows:
          print("No matching label rows found for specified images in branch '{CONSENSUS_BRANCH_NAME}'.")
          exit()

      print("Processing label rows for:", [row.data_title for row in label_rows])

      with project.create_bundle() as bundle:
          # Prepare for labeling
          for label_row in label_rows:
              label_row.initialise_labels(bundle=bundle)

      for label_row in label_rows:
          image_title = label_row.data_title  # Get the image title
          polygon_data = image_annotations.get(image_title, [])  # Get associated polygons

          if not polygon_data:
              print(f"No polygon data found for {image_title}, skipping.")
              continue

          # Retrieve the specified ontology object by title
          polygon_ontology_object = project.ontology_structure.get_child_by_title(
              title=ONTOLOGY_OBJECT_TITLE,
              type_=Object
          )

          # Iterate through each set of polygons in the image's annotation data
          for polygon_group in polygon_data:
              # Instantiate an object instance from the polygon ontology node
              polygon_object_instance = polygon_ontology_object.create_instance()

              # Set the coordinates for the polygon(s) (outer + inner if applicable)
              polygon_object_instance.set_for_frames(
                  coordinates=PolygonCoordinates(polygon_group),
                  frames=0,  # Apply to the specified frame
                  manual_annotation=True,  # Set to True for manual annotation
                  confidence=1.0,  # Confidence of your label
              )

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

      with project.create_bundle() as bundle:
          for label_row in label_rows:
              # Save the label row with the polygon object instance within the bundle
              label_row.save(bundle=bundle)

      print("Label rows updated with polygon instances.")

      ```

      ```python Multiple Polygons theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

      # Define coordinates for each image (multiple independent polygons)
      image_annotations = {
          "cherry-002-dup-003.jpg": [
              # Polygon 1
              [
                  [PointCoordinate(0.1, 0.1), PointCoordinate(0.3, 0.1), 
                   PointCoordinate(0.3, 0.3), PointCoordinate(0.1, 0.3)]
              ],
              # Polygon 2
              [
                  [PointCoordinate(0.6, 0.6), PointCoordinate(0.9, 0.6), 
                   PointCoordinate(0.9, 0.9), PointCoordinate(0.6, 0.9)]
              ]
          ],
          
          "cherry-002-dup-006.jpg": [
              # Polygon 1
              [
                  [PointCoordinate(0.2, 0.2), PointCoordinate(0.4, 0.2), 
                   PointCoordinate(0.4, 0.4), PointCoordinate(0.2, 0.4)]
              ],
              # Polygon 2
              [
                  [PointCoordinate(0.5, 0.5), PointCoordinate(0.7, 0.5), 
                   PointCoordinate(0.7, 0.7), PointCoordinate(0.5, 0.7)]
              ]
          ],
      }

      # Ensure SSH path and project id are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_ID, "Project id cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      # Get project and list label rows for the specified branch
      project = user_client.get_project(PROJECT_ID)
      all_label_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on images in `image_annotations`
      label_rows = [row for row in all_label_rows if row.data_title in image_annotations]

      if not label_rows:
          print(f"No matching label rows found for specified images in branch '{CONSENSUS_BRANCH_NAME}'.")
          exit()

      print("Processing label rows for:", [row.data_title for row in label_rows])

      with project.create_bundle() as bundle:
          # Prepare for labeling
          for label_row in label_rows:
              label_row.initialise_labels(bundle=bundle)

      for label_row in label_rows:
          image_title = label_row.data_title  # Get the image title
          polygon_data = image_annotations.get(image_title, [])  # Get associated polygons

          if not polygon_data:
              print(f"No polygon data found for {image_title}, skipping.")
              continue

          # Retrieve the specified ontology object by title
          polygon_ontology_object = project.ontology_structure.get_child_by_title(
              title=ONTOLOGY_OBJECT_TITLE,
              type_=Object
          )

          # Iterate through each independent polygon in the image's annotation data
          for polygon in polygon_data:
              # Instantiate an object instance from the polygon ontology node
              polygon_object_instance = polygon_ontology_object.create_instance()

              # Set the coordinates for each polygon separately
              polygon_object_instance.set_for_frames(
                  coordinates=PolygonCoordinates(polygon),
                  frames=0,  # Apply to the specified frame
                  manual_annotation=True,  # Set to True for manual annotation
                  confidence=1.0,  # Confidence of your label
              )

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

      with project.create_bundle() as bundle:
          for label_row in label_rows:
              # Save the label row with the polygon object instances within the bundle
              label_row.save(bundle=bundle)

      print("Label rows updated with multiple independent polygon instances.")


      ```

      ```python Donut with Object Inside theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

      # Define coordinates for each image (handling donut shapes and nested polygons)
      image_annotations = {
          "cherries-001.jpg": [
              # Donut shape: Outer ring + Inner ring
              [
                  [
                      PointCoordinate(1.000, 0.500), PointCoordinate(0.750, 0.933), 
                      PointCoordinate(0.250, 0.933), PointCoordinate(0.000, 0.500), 
                      PointCoordinate(0.250, 0.067), PointCoordinate(0.750, 0.067)  # Outer ring
                  ],
                  [
                      PointCoordinate(0.750, 0.500), PointCoordinate(0.625, 0.717), 
                      PointCoordinate(0.375, 0.717), PointCoordinate(0.250, 0.500), 
                      PointCoordinate(0.375, 0.284), PointCoordinate(0.625, 0.284)  # Inner ring (hole)
                  ]
              ],
              # Second polygon inside the hole
              [
                  [
                      PointCoordinate(0.550, 0.500), PointCoordinate(0.525, 0.575), 
                      PointCoordinate(0.475, 0.575), PointCoordinate(0.450, 0.500), 
                      PointCoordinate(0.475, 0.425), PointCoordinate(0.525, 0.425)
                  ]
              ]
          ],
          
          "cherries-010.jpg": [
              # Donut shape: Outer ring + Inner ring
              [
                  [
                      PointCoordinate(0.900, 0.400), PointCoordinate(0.700, 0.850), 
                      PointCoordinate(0.300, 0.850), PointCoordinate(0.100, 0.400), 
                      PointCoordinate(0.300, 0.100), PointCoordinate(0.700, 0.100)
                  ],
                  [
                      PointCoordinate(0.700, 0.400), PointCoordinate(0.600, 0.650), 
                      PointCoordinate(0.400, 0.650), PointCoordinate(0.300, 0.400), 
                      PointCoordinate(0.400, 0.200), PointCoordinate(0.600, 0.200)
                  ]
              ],
              # Second polygon inside the hole
              [
                  [
                      PointCoordinate(0.500, 0.500), PointCoordinate(0.550, 0.600), 
                      PointCoordinate(0.450, 0.600), PointCoordinate(0.400, 0.500), 
                      PointCoordinate(0.450, 0.400), PointCoordinate(0.550, 0.400)
                  ]
              ]
          ]
      }

      # Ensure SSH path and project ID are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_ID, "Project ID cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      # Get project and list label rows for the specified branch
      project = user_client.get_project(PROJECT_ID)
      all_label_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on images in `image_annotations`
      label_rows = [row for row in all_label_rows if row.data_title in image_annotations]

      if not label_rows:
          print(f"No matching label rows found for specified images in branch '{CONSENSUS_BRANCH_NAME}'.")
          exit()

      print("Processing label rows for:", [row.data_title for row in label_rows])

      with project.create_bundle() as bundle:
          # Prepare for labeling
          for label_row in label_rows:
              label_row.initialise_labels(bundle=bundle)

      for label_row in label_rows:
          image_title = label_row.data_title  # Get the image title
          polygon_data = image_annotations.get(image_title, [])  # Get associated polygons

          if not polygon_data:
              print(f"No polygon data found for {image_title}, skipping.")
              continue

          # Retrieve the specified ontology object by title
          polygon_ontology_object = project.ontology_structure.get_child_by_title(
              title=ONTOLOGY_OBJECT_TITLE,
              type_=Object
          )

          # Iterate through each group of polygons in the image's annotation data
          for polygon_group in polygon_data:
              # Instantiate an object instance from the polygon ontology node
              polygon_object_instance = polygon_ontology_object.create_instance()

              # Check if the polygon group contains multiple polygons (outer + inner ring)
              if len(polygon_group) > 1:
                  # Handle donut shape (outer ring + inner ring)
                  polygon_object_instance.set_for_frames(
                      coordinates=PolygonCoordinates(polygon_group),  # Multiple polygons
                      frames=0,  # Apply to the specified frame
                      manual_annotation=True,  # Set to True for manual annotation
                      confidence=1.0,  # Confidence of your label
                  )
              else:
                  # Handle single independent polygons inside the hole
                  polygon_object_instance.set_for_frames(
                      coordinates=PolygonCoordinates(polygon_group[0]),  # Single polygon
                      frames=0,  # Apply to the specified frame
                      manual_annotation=True,  # Set to True for manual annotation
                      confidence=1.0,  # Confidence of your label
                  )

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

      with project.create_bundle() as bundle:
          for label_row in label_rows:
              # Save the label row with the polygon object instances within the bundle
              label_row.save(bundle=bundle)

      print("Label rows updated with donut-shaped polygons and nested polygons.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="DEPRECATED - Polygons">
    **Example 1**

    Imports a single polygon (`Persimmon`) to a single image (`persimmon_001.jpg`).

    **Example 2**

    Imports three instances (tracking an object across three sequential frames: 143, 144, and 145) of a polygon (`Persimmon`) to a video (`Cherries_video.mp4`).

    **Example 3**

    Imports three polygons (`Persimmon`) to a single image (`persimmon_001.jpg`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 153, 154, 155, object 2 - frames 242, 244, 246, and object 3 - frames 343, 345, 347) of three polygons (`Persimmon`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Import Polygon Template theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"
      PROJECT_ID = "<project-unique-id>"
      CONSENSUS_BRANCH_NAME = "<name-of-your-label-branch>"  # Specify the label branch
      DATA_UNIT_TITLE = "<name-of-data-unit>"  # The title of the data unit (image or video)
      ONTOLOGY_OBJECT_TITLE = "<object-name>"  # The ontology object title for the polygon

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

      # Get the project and list label rows for the label branch
      project: Project = user_client.get_project(PROJECT_ID)
      consensus_branch_rows = project.list_label_rows_v2(
          branch_name=CONSENSUS_BRANCH_NAME,  # Use the label branch
          data_title_eq=DATA_UNIT_TITLE
      )

      if not consensus_branch_rows:
          print("No matching data units found in the specified branch.")
      else:
          print("Data units found:", [row.data_title for row in consensus_branch_rows])

      # Initialize labels for each selected label row in the label branch
      label_row = consensus_branch_rows[0]
      label_row.initialise_labels()

      # Find a polygon annotation object in the project ontology
      polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the polygon ontology node
      polygon_object_instance: ObjectInstance = polygon_ontology_object.create_instance()

      # Define the polygon coordinates
      polygon_coordinates = PolygonCoordinates([
          PointCoordinate(0.1, 0.2),
          PointCoordinate(0.3, 0.4),
          PointCoordinate(0.5, 0.6),
          PointCoordinate(0.7, 0.8)
      ])

      # Set the polygon label for the specified frame
      polygon_object_instance.set_for_frames(
          coordinates=polygon_coordinates,
          frames=0,  # Specify the frame number
          manual_annotation=False,  # Mark as a label
          confidence=1.0  # Optional confidence score
      )

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

      # Save the label row 
      label_row.save()
      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology
      DATA_UNIT_TITLE = "persimmon_001.jpg"  # Specific data unit title

      # Ensure SSH path and project id are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_ID, "Project id cannot be None"

      # Authenticate with Encord using access key
      user_client = EncordUserClient.create_with_ssh_private_key(
          Path(SSH_PATH).read_text()
      )

      # Get project and list label rows for the specified branch and data unit
      project = user_client.get_project(PROJECT_ID)
      all_label_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

      # Filter label rows based on the specified data unit title
      label_rows = [
          row for row in all_label_rows 
          if row.data_title == DATA_UNIT_TITLE
      ]

      if not label_rows:
          print(f"No matching label rows found for {DATA_UNIT_TITLE} in branch '{CONSENSUS_BRANCH_NAME}'.")
          exit()  # Nothing to do so exit early

      print("Label rows found:", [row.data_title for row in label_rows])

      with project.create_bundle() as bundle:
          # Prepare for labeling
          for label_row in label_rows:
              label_row.initialise_labels(bundle=bundle)

      for label_row in label_rows:
          # Retrieve the specified ontology object by title
          polygon_ontology_object = project.ontology_structure.get_child_by_title(
              title=ONTOLOGY_OBJECT_TITLE,
              type_=Object
          )

          # Instantiate an object instance from the polygon ontology node
          polygon_object_instance = polygon_ontology_object.create_instance()

          # The x,y coordinates of each polygon vertex
          polygon_object_instance.set_for_frames(
              coordinates=PolygonCoordinates(
                  [PointCoordinate(.1, .1), PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4)]
              ),
              frames=0,  # Apply to the specified frame
              manual_annotation=True,  # Set to True for manual annotation
              confidence=1.0,  # Confidence of your label
          )

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


      with project.create_bundle() as bundle:
          for label_row in label_rows:
              # Save the label row with the polygon object instance within the bundle
              label_row.save(bundle=bundle)

      print("Label rows updated with polygon instances.")
      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

      # Ensure SSH path and project id are set
      assert SSH_PATH, "SSH path cannot be None"
      assert PROJECT_ID, "Project id cannot be None"

      # 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)

      # Retrieve the label row for the specified data unit
      label_row = project.list_label_rows_v2(
          data_title_eq=DATA_UNIT_TITLE
      )[0]

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

      # Find the polygon annotation object in the project ontology
      polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Coordinates for each frame
      coordinates_per_frame = {
          143: PolygonCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
          144: PolygonCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
          145: PolygonCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
      }

      # Create and link polygon object instances for each frame
      for frame_number, coordinates in coordinates_per_frame.items():
          polygon_object_instance: ObjectInstance = polygon_ontology_object.create_instance()
          polygon_object_instance.set_for_frames(
              coordinates=coordinates,
              frames=frame_number,
              manual_annotation=True,  # Set to True for manual annotation
              confidence=1.0,  # Set confidence level as needed
          )
          
          # Link the object instance to the label row
          label_row.add_object_instance(polygon_object_instance)

      # Save the label row 
      label_row.save()
      print("Label row updated with polygon instances.")

      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "persimmon_001.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

      # 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]

      label_row.initialise_labels()

      # Find a polygon annotation object in the project ontology
      polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Function to create a polygon object instance
      def create_polygon_instance(ontology_object, coordinates, frame, manual_annotation=True, confidence=1.0):
          polygon_instance = ontology_object.create_instance()
          polygon_instance.set_for_frames(
              coordinates=coordinates,
              frames=frame,
              manual_annotation=manual_annotation,
              confidence=confidence,
          )
          return polygon_instance

      # Define coordinates for polygons
      polygon_coordinates = [
          PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4)]),
          PolygonCoordinates([PointCoordinate(.15, .15), PointCoordinate(.25, .25), PointCoordinate(.35, .35), PointCoordinate(.15, .45)]),
          PolygonCoordinates([PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4), PointCoordinate(.2, .5)]),
      ]

      # Create and link polygon instances for each set of coordinates
      for coords in polygon_coordinates:
          polygon_instance = create_polygon_instance(polygon_ontology_object, coords, frame=0)
          label_row.add_object_instance(polygon_instance)

      # Save the label row with polygon instances
      label_row.save()
      print("Label row updated with polygon instances.")

      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Persimmon"  # Name of object label in your Ontology

      # 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 polygon annotation object in the project ontology
      polygon_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Function to create and add a polygon instance
      def add_polygon_instance(label_row, ontology_object, coordinates_per_frame):
          polygon_instance = ontology_object.create_instance()

          for frame_number, coordinates in coordinates_per_frame.items():
              polygon_instance.set_for_frames(
                  coordinates=coordinates,
                  frames=frame_number,
                  manual_annotation=True,  # Set to True for manual annotation
                  confidence=1.0,  # Set confidence level as needed
              )
          
          # Link the object instance to the label row
          label_row.add_object_instance(polygon_instance)

      # Coordinates for each polygon
      coordinates_list = [
          {
              153: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              154: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              155: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
          },
          {
              242: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              244: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              246: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
          },
          {
              343: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              345: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
              347: PolygonCoordinates([PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]),
          },
      ]

      # Add polygon instances
      for coordinates in coordinates_list:
          add_polygon_instance(label_row, polygon_ontology_object, coordinates)

      # Save the label row with polygon instances
      label_row.save()
      print("Label row updated with polygon instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Polyline">
    **Example 1**

    Imports a single polyline (`Branch`) to a single image (`persimmon_001.jpg`).

    **Example 2**

    Imports three instances (tracking an object across three sequential frames: 146, 147, and 148) of a polygon (`Branch`) to a video (`Cherries_video.mp4`).

    **Example 3**

    Imports three polylines (`Branch`) to a single image (`persimmon_001.jpg`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 246, 247, 248, object 2 - frames 346, 347, 348, and object 3 - frames 446, 447, 448) of three polylines (`Branch`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Import Polyline Template theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_ID = "<project-unique-id>"  # Unique project id
      CONSENSUS_BRANCH_NAME = "<your-label-branch-name>"  # Specify your label branch
      DATA_UNIT_TITLE = "<name-of-data-unit>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<object-name>"  # Name of the polyline object in your ontology

      # 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 polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      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>,  # Replace with the actual frame number
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the polyline instance
      label_row.save()
      print("Label row updated with polyline instance.")

      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "apple_001.png"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Branch"  # Name of the polyline object in your ontology

      # 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 polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4)]
          ),
          # Add the polyline to the image
          frames=0,  # Specify the frame number
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the polyline instance 
      label_row.save()
      print("Label row updated with polyline instance.")

      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Branch"  # Name of the polyline object in your ontology

      # 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 polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()

      # Coordinates for each frame
      coordinates_per_frame = {
          146: PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]
          ),
          147: PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]
          ),
          148: PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .1), PointCoordinate(.3, .2), PointCoordinate(.1, .3)]
          ),
      }

      # Set coordinates for each frame in the polyline object instance
      for frame_number, coordinates in coordinates_per_frame.items():
          polyline_object_instance.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True
          )

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

      # Save the label row with the polyline instance
      label_row.save()
      print("Label row updated with polyline instance.")

      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "apple_001.png"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Branch"  # Name of the polyline object in your ontology

      # 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 polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Polyline 1 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance01: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance01.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.1, .1), PointCoordinate(.2, .2), PointCoordinate(.3, .3), PointCoordinate(.4, .4)]
          ),
          # Add the polyline to the image
          frames=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance01)
      # Polyline 1 - END

      # Polyline 2 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance02: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance02.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.15, .15), PointCoordinate(.25, .25), PointCoordinate(.35, .35), PointCoordinate(.45, .45)]
          ),
          # Add the polyline to the image
          frames=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance02)
      # Polyline 2 - END

      # Polyline 3 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance03: ObjectInstance = polyline_ontology_object.create_instance()

      # The x,y coordinates of each polyline vertex are specified as follows
      polyline_object_instance03.set_for_frames(
          coordinates=PolylineCoordinates(
              [PointCoordinate(.17, .17), PointCoordinate(.27, .27), PointCoordinate(.37, .37), PointCoordinate(.47, .47)]
          ),
          # Add the polyline to the image
          frames=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance03)
      # Polyline 3 - END

      # Save the label row with the polyline instances
      label_row.save()
      print("Label row updated with polyline instances.")
      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PolylineCoordinates, PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Branch"  # Name of the polyline object in your ontology

      # 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 polyline annotation object in the project ontology
      polyline_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Polyline 1 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance01: ObjectInstance = polyline_ontology_object.create_instance()

      coordinates_per_frame = {
          246: PolylineCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
          247: PolylineCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
          248: PolylineCoordinates(
              [PointCoordinate(.1, .1),
               PointCoordinate(.2, .1),
               PointCoordinate(.3, .2),
               PointCoordinate(.1, .3)]
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          polyline_object_instance01.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True
          )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance01)
      # Polyline 1 - END

      # Polyline 2 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance02: ObjectInstance = polyline_ontology_object.create_instance()

      coordinates_per_frame = {
          346: PolylineCoordinates(
              [PointCoordinate(.11, .11),
               PointCoordinate(.21, .11),
               PointCoordinate(.31, .21),
               PointCoordinate(.11, .31)]
          ),
          347: PolylineCoordinates(
              [PointCoordinate(.11, .11),
               PointCoordinate(.21, .11),
               PointCoordinate(.31, .21),
               PointCoordinate(.11, .31)]
          ),
          348: PolylineCoordinates(
              [PointCoordinate(.11, .11),
               PointCoordinate(.21, .11),
               PointCoordinate(.31, .21),
               PointCoordinate(.11, .31)]
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          polyline_object_instance02.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True
          )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance02)
      # Polyline 2 - END

      # Polyline 3 - START
      # Instantiate an object instance from the polyline ontology node
      polyline_object_instance03: ObjectInstance = polyline_ontology_object.create_instance()

      coordinates_per_frame = {
          446: PolylineCoordinates(
              [PointCoordinate(.21, .21),
               PointCoordinate(.22, .21),
               PointCoordinate(.23, .22),
               PointCoordinate(.21, .23)]
          ),
          447: PolylineCoordinates(
              [PointCoordinate(.21, .21),
               PointCoordinate(.22, .21),
               PointCoordinate(.23, .22),
               PointCoordinate(.21, .23)]
          ),
          448: PolylineCoordinates(
              [PointCoordinate(.21, .21),
               PointCoordinate(.22, .21),
               PointCoordinate(.23, .22),
               PointCoordinate(.21, .23)]
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          polyline_object_instance03.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True
          )

      # Link the object instance to the label row
      label_row.add_object_instance(polyline_object_instance03)
      # Polyline 3 - END

      # Save the label row with the polyline instances
      label_row.save()
      print("Label row updated with polyline instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Keypoint">
    **Example 1**

    Imports a single keypoint (`Pedicel`) to a single image (`blueberry_003.png`).

    **Example 2**

    Imports three instances (tracking an object across three sequential frames: 143, 144, and 145) of a keypoint (`Pedicel`) to a video (`Blueberries_video.mp4`).

    **Example 3**

    Imports three keypoints (`Pedicel`) to a single image (`blueberry_003.png`).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 143, 144, 145, object 2 - frames 242, 244, 246, and object 3 - frames 343, 345, 347) of three keypoints (`Pedicel`) to a video (`Blueberries_video.mp4`).

    <CodeGroup>
      ```python Import Keypoint Template theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_ID = "<project-unique-id>"  # Unique project id
      CONSENSUS_BRANCH_NAME = "<your-label-branch-name>"  # Specify your label branch
      DATA_UNIT_TITLE = "<name-of-data-unit>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<object-name>"  # Name of the keypoint object in your ontology

      # 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 keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()

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

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

      # Save the label row with the keypoint instance
      label_row.save()
      print("Label row updated with keypoint instance.")

      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "blueberry_003.png"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Pedicel"  # Name of the keypoint object in your ontology

      # 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 keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()

      # The x,y coordinates of the keypoint are specified as follows
      keypoint_object_instance.set_for_frames(
          coordinates=PointCoordinate(
              x=.1,
              y=.1
          ),
          # Add the keypoint to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the keypoint instance
      label_row.save()
      print("Label row updated with keypoint instance.")

      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Pedicel"  # Name of the keypoint object in your ontology

      # 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 keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()

      # Define coordinates for keypoints across frames
      coordinates_per_frame = {
          143: PointCoordinate(
              x=.1,
              y=.2
          ),
          144: PointCoordinate(
              x=.11,
              y=.22
          ),
          145: PointCoordinate(
              x=.12,
              y=.23
          ),
      }

      # Set keypoint coordinates for each frame
      for frame_number, coordinates in coordinates_per_frame.items():
          keypoint_object_instance.set_for_frames(
              coordinates=coordinates, 
              frames=frame_number, 
              manual_annotation=True,
              confidence=1.0  # Set confidence level as needed
          )

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

      # Save the label row with the keypoint instance
      label_row.save()
      print("Label row updated with keypoint instance.")

      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "blueberry_003.png"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Pedicel"  # Name of the keypoint object in your ontology

      # 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 keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Keypoint 1 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance01: ObjectInstance = keypoint_ontology_object.create_instance()

      # The x,y coordinates of the keypoint are specified as follows
      keypoint_object_instance01.set_for_frames(
          coordinates=PointCoordinate(
              x=.1,
              y=.1
          ),
          # Add the keypoint to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance01)
      # Keypoint 1 - END

      # Keypoint 2 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance02: ObjectInstance = keypoint_ontology_object.create_instance()

      # The x,y coordinates of the keypoint are specified as follows
      keypoint_object_instance02.set_for_frames(
          coordinates=PointCoordinate(
              x=.2,
              y=.2
          ),
          # Add the keypoint to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance02)
      # Keypoint 2 - END

      # Keypoint 3 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance03: ObjectInstance = keypoint_ontology_object.create_instance()

      # The x,y coordinates of the keypoint are specified as follows
      keypoint_object_instance03.set_for_frames(
          coordinates=PointCoordinate(
              x=.3,
              y=.3
          ),
          # Add the keypoint to the specified frame number
          frames=<frame-number>,  # Replace with the actual frame number
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance03)
      # Keypoint 3 - END

      # Save the label row with the keypoint instances
      label_row.save()
      print("Label row updated with keypoint instances.")

      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import PointCoordinate

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Pedicel"  # Name of the keypoint object in your ontology

      # 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 keypoint annotation object in the project ontology
      keypoint_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Keypoint 1 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance01: ObjectInstance = keypoint_ontology_object.create_instance()

      coordinates_per_frame = {
          143: PointCoordinate(
              x=.1,
              y=.2
          ),
          144: PointCoordinate(
              x=.11,
              y=.22
          ),
          145: PointCoordinate(
              x=.12,
              y=.23
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          keypoint_object_instance01.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance01)
      # Keypoint 1 - END

      # Keypoint 2 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance02: ObjectInstance = keypoint_ontology_object.create_instance()

      coordinates_per_frame = {
          242: PointCoordinate(
              x=.21,
              y=.22
          ),
          244: PointCoordinate(
              x=.211,
              y=.222
          ),
          246: PointCoordinate(
              x=.212,
              y=.223
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          keypoint_object_instance02.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance02)
      # Keypoint 2 - END

      # Keypoint 3 - START
      # Instantiate an object instance from the keypoint ontology node
      keypoint_object_instance03: ObjectInstance = keypoint_ontology_object.create_instance()

      coordinates_per_frame = {
          343: PointCoordinate(
              x=.31,
              y=.32
          ),
          345: PointCoordinate(
              x=.311,
              y=.322
          ),
          347: PointCoordinate(
              x=.312,
              y=.323
          ),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          keypoint_object_instance03.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(keypoint_object_instance03)
      # Keypoint 3 - END

      # Save the label row with the keypoint instances
      label_row.save()
      print("Label row updated with keypoint instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Bitmask">
    **Example 1:**

    Imports a single bitmask (`Blueberry`) to a single image (`blueberry_003.jpg`). For simplicity, the bitmask covers the entire image (image dimensions: 1254x836).

    **Example 2:**

    Imports three instances (tracking an object across three sequential frames: 156, 157, and 159) of a bitmask (`Blueberry`) to a video (`Blueberries_video.mp4`). For simplicity, the bitmask covers the entire frame (video dimensions: 1920x1080).

    **Example 3:**

    Imports three bitmasks (`Blueberry`) to a single image (`blueberry_003.jpg`). For simplicity, the bitmasks cover the entire image (image dimensions: 1254x836).

    **Example 4:**

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 156, 157, 158, object 2 - frames 256, 258, 259, and object 3 - frames 355, 357, 359) of three bitmasks (`Blueberry`) to a video (`Blueberries_video.mp4`). For simplicity, the bitmasks cover the entire frame (video dimensions: 1920x1080).

    <CodeGroup>
      ```python Template theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_ID = "<project-unique-id>"  # Unique project id
      CONSENSUS_BRANCH_NAME = "<your-label-branch-name>"  # Specify your label branch
      DATA_UNIT_TITLE = "<data-unit-name>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<bitmask-object-name>"  # Name of the bitmask object in your ontology

      # Prepare the mask itself.
      # For simplicity, we can just mask the whole image
      # Note: the size of the mask must be identical to the size of the image
      numpy_coordinates = np.ones((<y-axis-value>, <x-axis-value>))  # Replace with actual values

      # Ensure the image is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

      # 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 bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      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,
      )

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

      # Save the label row with the bitmask instance
      label_row.save()
      print("Label row updated with bitmask instance.")

      ```

      ```python Example 1 theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "blueberry_003.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry"  # Name of the bitmask object in your ontology

      # Prepare the mask itself.
      # For simplicity, we can just mask the whole image
      # Note: the size of the mask must be identical to the size of the image
      numpy_coordinates = np.ones((836, 1254))

      # Ensure the image is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

      # 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 bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      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,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the bitmask instance
      label_row.save()
      print("Label row updated with bitmask instance.")

      ```

      ```python Example 2 theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry"  # Name of the bitmask object in your ontology

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

      # Ensure the image/frame is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

      # 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 bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance: ObjectInstance = bitmask_ontology_object.create_instance()

      # Create and assign the bitmask coordinates for multiple frames
      coordinates_per_frame = {
          156: BitmaskCoordinates(numpy_coordinates),
          157: BitmaskCoordinates(numpy_coordinates),
          158: BitmaskCoordinates(numpy_coordinates),
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          bitmask_object_instance.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

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

      # Save the label row with the bitmask instance 
      label_row.save()
      print("Label row updated with bitmask instance.")

      ```

      ```python Example 3 theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "blueberry_003.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry"  # Name of the bitmask object in your ontology

      # Prepare the mask itself.
      # For simplicity, we can just mask the whole image
      # Note: the size of the mask must be identical to the size of the image
      numpy_coordinates = np.ones((836, 1254))

      # Ensure the image is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

      # 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 bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Bitmask 1 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance01: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      bitmask_object_instance01.set_for_frames(
          # Create coordinates from provided numpy bitmask
          coordinates=BitmaskCoordinates(numpy_coordinates),
          # Add the bitmask to the first frame
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance01)
      # Bitmask 1 - END

      # Bitmask 2 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance02: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      bitmask_object_instance02.set_for_frames(
          # Create coordinates from provided numpy bitmask
          coordinates=BitmaskCoordinates(numpy_coordinates),
          # Add the bitmask to the first frame
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance02)
      # Bitmask 2 - END

      # Bitmask 3 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance03: ObjectInstance = bitmask_ontology_object.create_instance()

      # The coordinates for the bitmask are specified as follows
      bitmask_object_instance03.set_for_frames(
          # Create coordinates from provided numpy bitmask
          coordinates=BitmaskCoordinates(numpy_coordinates),
          # Add the bitmask to the first frame
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance03)
      # Bitmask 3 - END

      # Save the label row with the bitmask instances
      label_row.save()
      print("Label row updated with bitmask instances.")

      ```

      ```python Example 4 theme={"dark"}
      # Import dependencies
      import numpy as np
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Object, ObjectInstance
      from encord.objects.coordinates import BitmaskCoordinates

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry"  # Name of the bitmask object in your ontology

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

      # Ensure the image/frame is in boolean format
      numpy_coordinates = numpy_coordinates.astype(bool)

      # 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 bitmask annotation object in the project ontology
      bitmask_ontology_object: Object = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE, type_=Object
      )

      # Bitmask 1 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance01: ObjectInstance = bitmask_ontology_object.create_instance()

      coordinates_per_frame = {
          156: BitmaskCoordinates(numpy_coordinates),
          157: BitmaskCoordinates(numpy_coordinates),
          158: BitmaskCoordinates(numpy_coordinates),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          bitmask_object_instance01.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance01)
      # Bitmask 1 - END

      # Bitmask 2 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance02: ObjectInstance = bitmask_ontology_object.create_instance()

      coordinates_per_frame = {
          256: BitmaskCoordinates(numpy_coordinates),
          258: BitmaskCoordinates(numpy_coordinates),
          259: BitmaskCoordinates(numpy_coordinates),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          bitmask_object_instance02.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance02)
      # Bitmask 2 - END

      # Bitmask 3 - START
      # Instantiate an object instance from the bitmask ontology node
      bitmask_object_instance03: ObjectInstance = bitmask_ontology_object.create_instance()

      coordinates_per_frame = {
          355: BitmaskCoordinates(numpy_coordinates),
          357: BitmaskCoordinates(numpy_coordinates),
          359: BitmaskCoordinates(numpy_coordinates),
      }
      for frame_number, coordinates in coordinates_per_frame.items():
          bitmask_object_instance03.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(bitmask_object_instance03)
      # Bitmask 3 - END

      # Save the label row with the bitmask instances
      label_row.save()
      print("Label row updated with bitmask instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Object Primitives">
    <Info>Before you can import Object Primitive labels into Encord, the Object Primitive Template MUST exist in Encord. [Use the UI to create the Object Primitive Template](/platform-documentation/Annotate/annotate-ontologies/annotate-working-with-ontologies#object-primitives) so you can visually inspect the Object Primitive.</Info>

    **Import Object Primitive labels**

    *Example 1*

    Imports a single object primitive (Ontology object = `Strawberry` Object Primitive name = `Triangle`) to a single image (`strawberries_10.jpg`).

    *Example 2*

    Imports three instances (tracking an object across three sequential frames: 163, 164, and 165) of a object primitive (Ontology object = `Strawberry` Object Primitive name = `Triangle`) to a video (`Cherries_video.mp4`).

    *Example 3*

    Imports three object primitives (Ontology object = `Strawberry` Object Primitive name = `Triangle`) to a single image (`strawberries_10.jpg`).

    *Example 4*

    Imports three instances (tracking 3 different objects across three frames: object 1 - frames 173, 174, 175, object 2 - frames 183, 184, 185, and object 3 - frames 193, 194, 195) of three object primitives (Ontology object = `Strawberry` Object Primitive name = `Triangle`) to a video (`Cherries_video.mp4`).

    <CodeGroup>
      ```python Import Skeleton Template theme={"dark"}
      # 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 = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_ID = "<project-unique-id>"  # Unique project id
      CONSENSUS_BRANCH_NAME = "<your-label-branch-name>"  # Specify your label branch
      DATA_UNIT_TITLE = "<name-of-data-unit>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<name-of-object-in-ontology>"  # Name of the object in your ontology
      SKELETON_TEMPLATE_NAME = "<name-of-object-primitive>"  # 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]

      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance: ObjectInstance = skeleton_ontology_object.create_instance()

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]
      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.x0, y=0.y0,  # Replace with actual coordinates
              name='point_0',
              color='#000000',
              value="point_0",
              feature_hash=skeleton_hashes[0]
          ),
          SkeletonCoordinate(
              x=0.x1, y=0.y1,  # Replace with actual coordinates
              name='point_1',
              color='#000000',
              value="point_1",
              feature_hash=skeleton_hashes[1]
          ),
          SkeletonCoordinate(
              x=0.x2, y=0.y2,  # Replace with actual coordinates
              name='point_2',
              color='#000000',
              value="point_2",
              feature_hash=skeleton_hashes[2]
          )
      ],
          name="<name-of-object-primitive>"  # Replace with the actual name
      )

      print(skeleton_coordinates)

      # The x,y coordinates of the skeleton are specified as follows
      skeleton_object_instance.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the skeleton instance
      label_row.save()
      print("Label row updated with skeleton instance.")


      ```

      ```python Example 1 theme={"dark"}
      # 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 = "7d4ead9c-4087-4832-a301-eb2545e7d43b"  # 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]

      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance: ObjectInstance = skeleton_ontology_object.create_instance()

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]
      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.25, y=0.25, 
              name='point_0', 
              color='#000000', 
              value="point_0", 
              feature_hash=skeleton_hashes[0]
          ), 
          SkeletonCoordinate(
              x=0.35, y=0.25, 
              name='point_1', 
              color='#000000', 
              value="point_1", 
              feature_hash=skeleton_hashes[1]
          ), 
          SkeletonCoordinate(
              x=0.25, y=0.35, 
              name='point_2', 
              color='#000000', 
              value="point_2", 
              feature_hash=skeleton_hashes[2]
          )
      ], 
      name=SKELETON_TEMPLATE_NAME)

      print(skeleton_coordinates)

      # The x,y coordinates of each skeleton vertex are specified as follows
      skeleton_object_instance.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=0,
          # There are multiple additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

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

      # Save the label row with the skeleton instance 
      label_row.save()
      print("Label row updated with skeleton instance.")

      ```

      ```python Example 2 theme={"dark"}
      # 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 = "b45deb4f-0732-4a89-bdc2-c1c345a82c02"  # Unique project id
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # 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]

      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance: ObjectInstance = skeleton_ontology_object.create_instance()

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]

      coordinates_per_frame = {
          163: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          164: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          165: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          )
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          skeleton_object_instance.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

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

      # Save the label row with the skeleton instance
      label_row.save()
      print("Label row updated with skeleton instance.")

      ```

      ```python Example 3 theme={"dark"}
      # 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()

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]
      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.25, y=0.25, 
              name='point_0', 
              color='#000000', 
              value="point_0", 
              feature_hash=skeleton_hashes[0]
          ), 
          SkeletonCoordinate(
              x=0.35, y=0.25, 
              name='point_1', 
              color='#000000', 
              value="point_1", 
              feature_hash=skeleton_hashes[1]
          ), 
          SkeletonCoordinate(
              x=0.25, y=0.35, 
              name='point_2', 
              color='#000000', 
              value="point_2", 
              feature_hash=skeleton_hashes[2]
          )
      ], 
      name="Triangle")
      print(skeleton_coordinates)

      # Set the skeleton coordinates for the specified frames
      skeleton_object_instance_01.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=135-137, 
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_01)
      # OBJECT PRIMITIVE 1 - END

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

      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.45, y=0.45, 
              name='point_0', 
              color='#000000', 
              value="point_0", 
              feature_hash=skeleton_hashes[0]
          ), 
          SkeletonCoordinate(
              x=0.65, y=0.45, 
              name='point_1', 
              color='#000000', 
              value="point_1", 
              feature_hash=skeleton_hashes[1]
          ), 
          SkeletonCoordinate(
              x=0.45, y=0.65, 
              name='point_2', 
              color='#000000', 
              value="point_2", 
              feature_hash=skeleton_hashes[2]
          )
      ], 
      name="Triangle")
      print(skeleton_coordinates)

      # Set the skeleton coordinates for the specified frames
      skeleton_object_instance_02.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_02)
      # OBJECT PRIMITIVE 2 - END

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

      skeleton_coordinates: SkeletonCoordinates = SkeletonCoordinates(values=[
          SkeletonCoordinate(
              x=0.75, y=0.75, 
              name='point_0', 
              color='#000000', 
              value="point_0", 
              feature_hash=skeleton_hashes[0]
          ), 
          SkeletonCoordinate(
              x=0.95, y=0.75, 
              name='point_1', 
              color='#000000', 
              value="point_1", 
              feature_hash=skeleton_hashes[1]
          ), 
          SkeletonCoordinate(
              x=0.75, y=0.95, 
              name='point_2', 
              color='#000000', 
              value="point_2", 
              feature_hash=skeleton_hashes[2]
          )
      ], 
      name="Triangle")
      print(skeleton_coordinates)

      # Set the skeleton coordinates for the specified frames
      skeleton_object_instance_03.set_for_frames(
          coordinates=skeleton_coordinates,
          # Add the skeleton to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_03)
      # OBJECT PRIMITIVE 3 - END

      # Save the label row with the skeleton instances
      label_row.save()
      print("Label row updated with skeleton instances.")

      ```

      ```python Example 4 theme={"dark"}
      # 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 = "0adfb083-9b69-4a09-8084-7fb432ecdfeb"  # Unique project id
      CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
      DATA_UNIT_TITLE = "Cherries_video.mp4"  # 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]

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

      skeleton_hashes = [coord.feature_hash for coord in skeleton_template.skeleton.values()]

      coordinates_per_frame = { 
          173: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          174: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          175: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          )
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          skeleton_object_instance_01.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_01)
      # Skeleton 1 - END

      # Skeleton 2 - START
      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance_02: ObjectInstance = skeleton_ontology_object.create_instance()

      coordinates_per_frame = { 
          183: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          184: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          185: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          )
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          skeleton_object_instance_02.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_02)
      # Skeleton 2 - END

      # Skeleton 3 - START
      # Instantiate an object instance from the skeleton ontology node
      skeleton_object_instance_03: ObjectInstance = skeleton_ontology_object.create_instance()

      coordinates_per_frame = { 
          193: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          194: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          ),
          195: SkeletonCoordinates(
              values=[
                  SkeletonCoordinate(x=0.25, y=0.25, name='point_0', color='#000000', value="point_0", feature_hash=skeleton_hashes[0]),
                  SkeletonCoordinate(x=0.35, y=0.25, name='point_1', color='#000000', value="point_1", feature_hash=skeleton_hashes[1]),
                  SkeletonCoordinate(x=0.25, y=0.35, name='point_2', color='#000000', value="point_2", feature_hash=skeleton_hashes[2])
              ],
              name="Triangle"
          )
      }

      for frame_number, coordinates in coordinates_per_frame.items():
          skeleton_object_instance_03.set_for_frames(
              coordinates=coordinates, frames=frame_number, manual_annotation=True, confidence=1.0
          )

      # Link the object instance to the label row
      label_row.add_object_instance(skeleton_object_instance_03)
      # Skeleton 3 - END

      # Save the label row with the skeleton instances 
      label_row.save()

      print("Label row updated with skeleton instances.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Radio Button">
    **Example 1:**

    Imports a radio button classification (`Blueberry or Cherry?`) to a single image (`blueberry_003.jpg`).

    **Example 2:**

    Imports a radio button classification (`Blueberry or Cherry?`) across a range of sequential frames: 193 to 197) to a video (`Blueberries_video.mp4`).

    <CodeGroup>
      ```python Radio Button Template theme={"dark"}
      # 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 = "<file-path-to-ssh-private-key>"  # Path to your SSH private key
      PROJECT_ID = "<unique-project-id>"  # Unique project id
      CONSENSUS_BRANCH_NAME = "<your-label-branch-name>"  # Specify your label branch
      DATA_UNIT_TITLE = "<data-unit-name>"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "<classification-name>"  # Name of the classification in your ontology
      RADIO_BUTTON_OPTION_TITLE = "<radio-button-option-title>"  # Title of the radio button option
      RADIO_BUTTON_OPTION = "<radio-button-option>"  # Specify the answer for the radio button option

      # 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 apply classification 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 the radio classification in the project ontology
      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific radio button option
      blueberry_option = radio_ontology_classification.get_child_by_title(
          title=RADIO_BUTTON_OPTION_TITLE, type_=Option
      )

      # Create an instance of the radio classification
      radio_classification_instance = radio_ontology_classification.create_instance()

      # Set the answer for the classification instance
      radio_classification_instance.set_answer(
          answer=RADIO_BUTTON_OPTION
      )

      # Set the classification for the specified frame
      radio_classification_instance.set_for_frames(
          # Add the classification to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(radio_classification_instance)

      # Save the label row with the classification instance
      label_row.save()

      print("Label row updated with classification instance.")

      ```

      ```python Example 1 theme={"dark"}
      # 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 = "blueberry_003.jpg"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Blueberry or Cherry?"  # Name of the classification in your ontology
      RADIO_BUTTON_OPTION_TITLE = "Blueberry"  # Title of the radio button option

      # 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 apply classification 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 the radio classification in the project ontology
      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific radio button option
      blueberry_option = radio_ontology_classification.get_child_by_title(
          title=RADIO_BUTTON_OPTION_TITLE, type_=Option
      )

      # Create an instance of the radio classification
      radio_classification_instance = radio_ontology_classification.create_instance()

      # Set the answer for the classification instance
      radio_classification_instance.set_answer(
          answer=blueberry_option
      )

      # Set the classification for the specified frame
      radio_classification_instance.set_for_frames(
          # Add the classification to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(radio_classification_instance)

      # Save the label row with the classification instance 
      label_row.save()

      print("Label row updated with classification instance.")

      ```

      ```python Example 2 theme={"dark"}
      # 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
      from encord.objects.frames import Range

      # 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 = "Blueberry or Cherry?"  # Name of the classification in your ontology
      RADIO_BUTTON_OPTION_TITLE = "Blueberry"  # Title of the radio button option

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

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

      # Specify the data unit to add classification 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 the radio classification in the project ontology
      radio_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific radio button option
      blueberry_option = radio_ontology_classification.get_child_by_title(
          title=RADIO_BUTTON_OPTION_TITLE, type_=Option
      )

      # Create an instance of the radio classification
      radio_classification_instance = radio_ontology_classification.create_instance()

      # Set the answer for the classification instance
      radio_classification_instance.set_answer(
          answer=blueberry_option,
      )

      # Set the classification for the specified frame range
      radio_classification_instance.set_for_frames(
          frames=Range(start=160, end=165),
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(radio_classification_instance)

      # Save the label row with the classification instance
      label_row.save()

      print("Label row updated with classification instance.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Checklist">
    **Example 1:**

    Imports a checklist classification (`Many types of fruit?`) to a single image (`apple_003.jpg`). The selected items from the list are `apple` and `kiwi`.

    **Example 2:**

    Imports a checklist classification (`Many types of fruit?`) across a range of sequential frames: 193 to 197) to a video (`Blueberries_video.mp4`). The selected items from the list are `apple` and `kiwi`.

    <CodeGroup>
      ```python Checklist Template theme={"dark"}
      # 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

      # 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 add classification 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 the checklist classification in the project ontology
      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific options in the checklist
      apple_option = checklist_ontology_classification.get_child_by_title(
          title=APPLE_OPTION_TITLE, type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title=KIWI_OPTION_TITLE, type_=Option
      )

      # Create an instance of the checklist classification
      checklist_classification_instance = checklist_ontology_classification.create_instance()

      # Set the answers for the classification instance
      checklist_classification_instance.set_answer(
          [apple_option, kiwi_option]
      )

      # Set the classification for the specified frame
      checklist_classification_instance.set_for_frames(
          # Add the classification to the image
          frames=177,
          # Additional fields that can be set optionally:
          manual_annotation=True,
          confidence=1.0,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(checklist_classification_instance)

      # Save the label row with the classification instance
      label_row.save()

      print("Label row updated with checklist classification instance.")

      ```

      ```python Example 1 theme={"dark"}
      # 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 = "apple_003.jpg"  # 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

      # 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 add classification 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 the checklist classification in the project ontology
      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific options in the checklist
      apple_option = checklist_ontology_classification.get_child_by_title(
          title=APPLE_OPTION_TITLE, type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title=KIWI_OPTION_TITLE, type_=Option
      )

      # Create an instance of the checklist classification
      checklist_classification_instance = checklist_ontology_classification.create_instance()

      # Set the answers for the classification instance
      checklist_classification_instance.set_answer(
          [apple_option, kiwi_option]
      )

      # Set the classification for the specified frame
      checklist_classification_instance.set_for_frames(
          # Add the classification to the image
          frames=0,
          # Additional fields that can be set optionally:
          manual_annotation=True,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(checklist_classification_instance)

      # Save the label row with the classification instance
      label_row.save()
      print("Label row updated with checklist classification instance.")

      ```

      ```python Example 2 theme={"dark"}
      # 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
      from encord.objects.frames import Range

      # 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

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

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

      # Specify the data unit to add classification 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 the checklist classification in the project ontology
      checklist_ontology_classification: Classification = project.ontology_structure.get_child_by_title(
          title=ONTOLOGY_OBJECT_TITLE,
          type_=Classification,
      )

      # Find the specific options in the checklist
      apple_option = checklist_ontology_classification.get_child_by_title(
          title=APPLE_OPTION_TITLE, type_=Option
      )

      kiwi_option = checklist_ontology_classification.get_child_by_title(
          title=KIWI_OPTION_TITLE, type_=Option
      )

      # Create an instance of the checklist classification
      checklist_classification_instance = checklist_ontology_classification.create_instance()

      # Set the answers for the classification instance
      checklist_classification_instance.set_answer(
          [apple_option, kiwi_option]
      )

      # Set the classification for the specified frame range
      checklist_classification_instance.set_for_frames(
          frames=Range(start=193, end=197),
          # Additional fields that can be set optionally:
          manual_annotation=True,
      )

      # Link the classification instance to the label row
      label_row.add_classification_instance(checklist_classification_instance)

      # Save the label row with the classification instance
      label_row.save()
      print("Label row updated with checklist classification instance.")

      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

This simple example imports a bounding box model label to all data units in the label branch.

```python Store labels Boilerplate theme={"dark"}
# Import dependencies
import os
from encord import EncordUserClient, Project
from encord.objects import LabelRowV2, Object, OntologyStructure, ObjectInstance

from encord.objects.coordinates import BoundingBoxCoordinates, RotatableBoundingBoxCoordinates, PolygonCoordinates, PolylineCoordinates, PointCoordinate, BitmaskCoordinates


# Configuration
SSH_PATH = "file-path-to-your-ssh-key"
PROJECT_ID = "unique-id-for-project"

# Specify a label_rows_v2 branch name for your labels.
CONSENSUS_BRANCH_NAME = "name-of-your-label-branch"

assert SSH_PATH is not None, "SSH path cannot be None"
assert PROJECT_ID is not None, "Project id cannot be None"

# Authenticate with Encord
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Access the project and prepare the branch for labels
project = user_client.get_project(PROJECT_ID)
consensus_branch_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

if len(consensus_branch_rows) > 0:
  print("Branch is:", consensus_branch_rows[0].branch_name)

ontology_object = project.ontology_structure.objects[0]
with project.create_bundle() as bundle:
    for row in consensus_branch_rows:
        row.initialise_labels(bundle=bundle)

for row in consensus_branch_rows:
    inst = ontology_object.create_instance()
    inst.set_for_frames(
        coordinates=BoundingBoxCoordinates(
            height=0.8,
            width=0.8,
            top_left_x=0.1,
            top_left_y=0.1,
        ),
        # Add the bounding box to the first frame
        frames=0,
        # There are multiple additional fields that can be set optionally:
        manual_annotation=False,
    )
    row.add_object_instance(inst)

with project.create_bundle() as bundle:
    for row in consensus_branch_rows:
    row.save(bundle=bundle)

```

This simple example imports a bounding box model label to all data units in the label branch.

```python Store labels Boilerplate theme={"dark"}
# Import dependencies
import os
from encord import EncordUserClient, Project
from encord.objects import LabelRowV2, Object, OntologyStructure, ObjectInstance

from encord.objects.coordinates import BoundingBoxCoordinates, RotatableBoundingBoxCoordinates, PolygonCoordinates, PolylineCoordinates, PointCoordinate, BitmaskCoordinates


# Configuration
SSH_PATH = "file-path-to-your-ssh-key"
PROJECT_HASH = "unique-id-for-project"

# Specify a label_rows_v2 branch name for your labels.
CONSENSUS_BRANCH_NAME = "name-of-your-label-branch"

assert SSH_PATH is not None, "SSH path cannot be None"
assert PROJECT_ID is not None, "Project ID cannot be None"

# Authenticate with Encord
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Access the project and prepare the branch for labels
project = user_client.get_project(PROJECT_HASH)
consensus_branch_rows = project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)

if len(consensus_branch_rows) > 0:
  print("Branch is:", consensus_branch_rows[0].branch_name)

ontology_object = project.ontology_structure.objects[0]
with project.create_bundle() as bundle:
    for row in consensus_branch_rows:
        row.initialise_labels(bundle=bundle)

for row in consensus_branch_rows:
    inst = ontology_object.create_instance()
    inst.set_for_frames(
        coordinates=BoundingBoxCoordinates(
            height=0.8,
            width=0.8,
            top_left_x=0.1,
            top_left_y=0.1,
        ),
        # Add the bounding box to the first frame
        frames=0,
        # There are multiple additional fields that can be set optionally:
        manual_annotation=False,
    )
    row.add_object_instance(inst)

with project.create_bundle() as bundle:
    for row in consensus_branch_rows:
    row.save(bundle=bundle)

```

### Import COCO Labels to Consensus Branches

The following code imports COCO labels as predictions for Active.

For more information on [importing COCO labels into Encord](/sdk-documentation/sdk-labels/sdk-import-coco-labels), refer to our documentation.

Replace the following:

* `<private_key_path>` with the file path to your SSH private key.

* `encord-<name-of-your-consensus-branch>` with the name of your label branch.

* `<project_hash>` with the Project ID for your Project.

* `COCOimportfile.json` with the full path of the COCO file containing the predictions you want to import.

```python COCO Label import as Predictions theme={"dark"}

import json
from pathlib import Path
from encord.utilities.coco.datastructure import FrameIndex
from encord import EncordUserClient
from encord.exceptions import OntologyError

# Authenticate client
SSH_PATH = "file-path-to-your-ssh-key"

# Specify a Project to import your predictions to. This Project must already exist in Encord.
PROJECT_HASH = "unique-id-for-project"

# Specify a label_rows_v2 branch name for your labels.
CONSENSUS_BRANCH_NAME = "encord-<name-of-your-consensus-branch>"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Replace with your project ID
project = user_client.get_project(PROJECT_ID)

# Load the COCO annotations JSON file
# Replace 'COCOimportfile.json' with the full path to your COCO file
coco_file = Path("COCOimportfile.json")
labels_dict = json.loads(coco_file.read_text())

# Build a mapping from COCO category IDs to the feature hashes in your Encord Ontology. 
category_id_to_feature_hash = {}
ont_struct = project.ontology_structure
for coco_category in labels_dict["categories"]:
    try:
        ont_obj = ont_struct.get_child_by_title(coco_category["name"])
        category_id_to_feature_hash[coco_category["id"]] = ont_obj.feature_node_hash
    except OntologyError:
        print(f"Could not match {coco_category['name']} in the Ontology. Import will crash if these are present.")

# Build a mapping from COCO image IDs to Encord frame indices
# This is only applicable for images, image groups, image sequences, videos, and DICOM series
image_id_to_frame_index = {}
data_title_to_label_row = {lr.data_title: lr for lr in project.list_label_rows_v2(branch_name=CONSENSUS_BRANCH_NAME)}
for img in labels_dict['images']:
    if "video_title" in img.keys():
        lr = data_title_to_label_row[img["video_title"]]
        frame_num = int(img["file_name"].split('/')[-1].split(".")[0])
    else:
        lr = data_title_to_label_row[img['image_title']]
        frame_num = 0

    # Creates a mapping between the COCO image IDs and the corresponding frame indices in Encord
    # In this example, the target frame is 0 because the files in the sample project are single images
    image_id_to_frame_index[img['id']] = FrameIndex(lr.data_hash, frame=frame_num)

# Import the COCO labels into Encord
project.import_coco_labels(
    labels_dict,
    category_id_to_feature_hash,
    image_id_to_frame_index,
    branch_name=CONSENSUS_BRANCH_NAME,
)

```

## Verify Label Import

After importing your labels, verify that your labels imported.

The following code returns all labels and predictions on all branches.

```python theme={"dark"}

# Import dependencies
from encord import EncordUserClient
import json

SSH_PATH = "file-path-of-your-ssh-key"
PROJECT_HASH = "unique-id-for-your-project"

# Instantiate client. Replace \<private_key_path> with the path to the file containing your private key.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify Project. Replace <project_hash> with the ID of the Project you want to export labels for.
project = user_client.get_project(PROJECT_HASH)

# Downloads a local copy of all the labels
# Without the include_all_label_branches flag only the MAIN branch labels export
label_rows = project.list_label_rows_v2(include_all_label_branches=True) 

# Initialize label rows using bundles
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    # Here we have the label row for the branch, but without labels themselves downloaded
    print(f"Title: {label_row.data_title}, branch: {label_row.branch_name}")

    # Print essential label information for all objects
    for object_instance in label_row.get_object_instances():
        print (f"objectHash: {object_instance.object_hash}")
        print (f"Object name: {object_instance.object_name}")
        print (f"featureHash: {object_instance.feature_hash}")
        print (f"uid: {object_instance.ontology_item.uid}")
        print (f"Object color: {object_instance.ontology_item.color}")
        print (f"Ontology shape: {object_instance.ontology_item.shape}")

        # Print the frame number and the location of the object on the frame
        for annotation in object_instance.get_annotations():
            print(f"Frame {annotation.frame} -> {annotation.coordinates}")

        # Print all attributes 
        for attribute in object_instance.ontology_item.attributes:
            print (attribute, object_instance)

    # Print all essential classification information
    for classification_instance in label_row.get_classification_instances():
        print (f"classificationHash: {classification_instance.classification_hash}")
        print (f"Classification name: {classification_instance.classification_name}")
        print (f"featureHash: {classification_instance.feature_hash}")
        print (f"Classification answer: {classification_instance.get_answer().value}")
        print (f"Classification answer hash: {classification_instance.get_answer().feature_node_hash}")


        # Print the frame number(s) that a classification appears on
        for annotation in classification_instance.get_annotations():
            print(f"Classification appears on frame: {annotation.frame}")

```


# Label Spaces: Code Examples
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-label-spaces-examples



Label Spaces are the objects returned by [`LabelRowV2.get_spaces()`](/sdk-documentation/sdk-references/objects.ontology_labels_impl) and `LabelRowV2.get_space()`. Each Space manages the object and classification instances for one data unit within a Label Row, and every modality has its own Space class in the [`objects.spaces`](/sdk-documentation/sdk-references/objects.spaces.base_space) module.

The examples below are grouped by the **four labelling patterns** the Space classes fall into. Pick the one that matches your data:

| Pattern                | Space classes                                                                   | How you position a label            |
| ---------------------- | ------------------------------------------------------------------------------- | ----------------------------------- |
| Geometric single-frame | `ImageSpace`                                                                    | `coordinates` only (no frames)      |
| Multi-frame            | `VideoSpace` (video & image sequence), `MedicalSpace` (DICOM/NIfTI), `PdfSpace` | `frames=` **and** `coordinates=`    |
| Range                  | `AudioSpace`, `TextSpace`, `HTMLSpace`, `TimeSeriesSpace`                       | `ranges=`                           |
| Point cloud            | `PointCloudFileSpace`                                                           | `ranges=` (or an Encord RLE string) |

<Info>
  For the full end-to-end Data Group workflow (root spaces, multi-layer groups, `layout_key` targeting), see [Data Groups & Label Spaces](/sdk-documentation/sdk-labels/sdk-data-group-labels).
</Info>

## Get a Space

Every Space is obtained from an initialized Label Row. You can list all Spaces, or fetch a specific one by storage-item ID or Data Group `layout_key`.

<Tip>
  `get_space()` requires the `type_` argument so the SDK returns the correctly typed Space. Identify the Space using **either**:

  * A storage item's unique ID: `lr.get_space(id="7E3KERd9arYTiPicaijP6c1LfI73", type_="image")`
  * A [Data Group](/sdk-documentation/index-sdk/sdk-data-groups) layout key: `lr.get_space(layout_key="left-camera", type_="video")`

  Using `layout_key`s lets you reuse the same code across multiple Label Rows without looking up storage-item IDs.
</Tip>

```python List all Spaces in a Label Row theme={"dark"}
from encord import EncordUserClient, Project

SSH_PATH = "<private_key_path>"   # Path to your SSH private key
PROJECT_ID = "<project_id>"       # Unique Project ID
DATA_TITLE = "<data_unit_title>"  # Title of the data unit

user_client = 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",
)

project: Project = user_client.get_project(PROJECT_ID)
lr = project.list_label_rows_v2(data_title_eq=DATA_TITLE)[0]
lr.initialise_labels()  # Spaces are only populated after initializing labels

for space in lr.get_spaces():
    print(
        f"space_id: {space.space_id}, "
        f"file_name: {space.metadata.file_name}, "
        f"layout_key: {space.metadata.layout_key}"
    )
```

## Shared `Space` methods

Every Space subclass inherits these read and remove methods from the base [`Space`](/sdk-documentation/sdk-references/objects.spaces.base_space) class, regardless of modality.

<CodeGroup>
  ```python Read instances and annotations theme={"dark"}
  # `space` is any Space obtained from lr.get_space(...) / lr.get_spaces()

  # All object / classification instances on the space
  objects = space.get_object_instances()
  classifications = space.get_classification_instances()

  # Lazily-created annotations (returned as an iterator)
  for annotation in space.get_annotations(type_="object"):
      print(annotation.object_hash, annotation.confidence, annotation.last_edited_by)

  # Filter to specific instance hashes
  for annotation in space.get_annotations(
      type_="object",
      filter_instance_hashes=["<object_hash_1>", "<object_hash_2>"],
  ):
      print(annotation.object_hash)
  ```

  ```python Remove instances theme={"dark"}
  # Remove by hash. Returns the removed instance, or None if it wasn't present.
  space.remove_object_instance(object_hash="<object_hash>")
  space.remove_classification_instance(classification_hash="<classification_hash>")

  # Persist the changes
  lr.save()
  ```
</CodeGroup>

## Image space (geometric, single-frame)

`ImageSpace` handles a single image. Objects are positioned with `coordinates` **only** — there is no `frames` argument. Classifications apply to the whole image.

```python ImageSpace theme={"dark"}
from encord import EncordUserClient, Project
from encord.objects import Object, Classification, ObjectInstance, ClassificationInstance
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.objects.options import Option

SSH_PATH = "<private_key_path>"
PROJECT_ID = "<project_id>"
DATA_TITLE = "<data_unit_title>"
SPACE_ID = "<storage_item_id>"

user_client = 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",
)
project: Project = user_client.get_project(PROJECT_ID)
lr = project.list_label_rows_v2(data_title_eq=DATA_TITLE)[0]
lr.initialise_labels()

image_space = lr.get_space(id=SPACE_ID, type_="image")

# Build instances from the Ontology
ontology = project.ontology_structure
box_object: Object = ontology.get_child_by_title(title="Vehicle", type_=Object)
day_night: Classification = ontology.get_child_by_title(title="Day or Night", type_=Classification)

bb_inst: ObjectInstance = box_object.create_instance()
cls_inst: ClassificationInstance = day_night.create_instance()
cls_inst.set_answer(answer=day_night.get_child_by_title(title="Day", type_=Option))

# Add an object — coordinates only, no frames for images
image_space.put_object_instance(
    bb_inst,
    BoundingBoxCoordinates(top_left_x=0.6, top_left_y=0.4, width=0.3, height=0.2),
    on_overlap="replace",   # "error" (default) | "replace"
    confidence=0.95,
    manual_annotation=True,
)

# Add a classification to the image
image_space.put_classification_instance(cls_inst, on_overlap="replace")

lr.save()
```

<Tip>
  For bitmask objects, pass an Encord-compatible RLE **string** as the coordinates instead of a `BoundingBoxCoordinates`/polygon object. Convert COCO/pycocotools RLE first with `encord.common.bitmask_operations.coco_rle_to_encord_rle`.
</Tip>

## Video space (multi-frame)

`VideoSpace` (also used for image sequences) and the other multi-frame spaces (`MedicalSpace` for DICOM/NIfTI, `PdfSpace`) require **both** `frames=` and `coordinates=`. Iterating annotations exposes the `frame` each annotation sits on.

```python VideoSpace theme={"dark"}
from encord import EncordUserClient, Project
from encord.objects import Object, ObjectInstance
from encord.objects.coordinates import BoundingBoxCoordinates

SSH_PATH = "<private_key_path>"
PROJECT_ID = "<project_id>"
DATA_TITLE = "<data_unit_title>"
SPACE_ID = "<storage_item_id>"

user_client = 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",
)
project: Project = user_client.get_project(PROJECT_ID)
lr = project.list_label_rows_v2(data_title_eq=DATA_TITLE)[0]
lr.initialise_labels()

video_space = lr.get_space(id=SPACE_ID, type_="video")

ontology = project.ontology_structure
person: Object = ontology.get_child_by_title(title="Person", type_=Object)
person_inst: ObjectInstance = person.create_instance()

# Place the object across a set of frames
video_space.put_object_instance(
    person_inst,
    frames=[0, 1, 2],
    coordinates=BoundingBoxCoordinates(top_left_x=0.6, top_left_y=0.4, width=0.3, height=0.2),
    on_overlap="replace",   # "error" (default) | "replace"
)

# Read back per-frame annotations
for annotation in video_space.get_annotations(type_="object"):
    print(f"frame {annotation.frame}: {annotation.coordinates}")

lr.save()
```

<Note>
  For DICOM/NIfTI use `type_="medical"`, and for PDFs use `type_="pdf"` (where `frames` refers to the page number). The `frames=`/`coordinates=` call is identical.
</Note>

## Audio space (range)

Range spaces — `AudioSpace`, `TextSpace`, `HTMLSpace`, `TimeSeriesSpace` — position objects over one-dimensional `ranges` instead of frames. `get_object_ranges()` returns the ranges an instance occupies, and range `on_overlap` additionally supports `"merge"`.

```python AudioSpace theme={"dark"}
from encord import EncordUserClient, Project
from encord.objects import Object, ObjectInstance
from encord.objects.frames import Range

SSH_PATH = "<private_key_path>"
PROJECT_ID = "<project_id>"
DATA_TITLE = "<data_unit_title>"
SPACE_ID = "<storage_item_id>"

user_client = 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",
)
project: Project = user_client.get_project(PROJECT_ID)
lr = project.list_label_rows_v2(data_title_eq=DATA_TITLE)[0]
lr.initialise_labels()

audio_space = lr.get_space(id=SPACE_ID, type_="audio")

ontology = project.ontology_structure
speaker: Object = ontology.get_child_by_title(title="Speaker", type_=Object)
speaker_inst: ObjectInstance = speaker.create_instance()

# Add the object to one or more ranges (a single Range or a list of Ranges)
audio_space.put_object_instance(
    speaker_inst,
    [Range(start=100, end=2000), Range(start=3000, end=4500)],
    on_overlap="merge",   # "error" (default) | "merge" | "replace"
)

# Inspect the ranges an instance occupies
print(audio_space.get_object_ranges(speaker_inst))

# Range annotations expose `.ranges`
for annotation in audio_space.get_annotations(type_="object"):
    print(annotation.object_hash, annotation.ranges)

lr.save()
```

<Note>
  `TextSpace`, `HTMLSpace`, and `TimeSeriesSpace` follow the same `ranges=` pattern. HTML uses `HtmlRange`/`HtmlNode` (`from encord.objects.html_node import HtmlRange, HtmlNode`) instead of `Range`.
</Note>

## Point cloud space

`PointCloudFileSpace` is a range space for 3D scenes. Segmentation objects are positioned either with `Range` objects over point indices or with an Encord-compatible RLE **string**. Its `metadata` is a `SceneMetadata` (exposing `stream_id`, `uri`, and `event_index`).

```python PointCloudFileSpace theme={"dark"}
from encord import EncordUserClient, Project
from encord.objects import Object, ObjectInstance
from encord.objects.frames import Range

SSH_PATH = "<private_key_path>"
PROJECT_ID = "<project_id>"
DATA_TITLE = "<data_unit_title>"
SPACE_ID = "<storage_item_id>"

user_client = 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",
)
project: Project = user_client.get_project(PROJECT_ID)
lr = project.list_label_rows_v2(data_title_eq=DATA_TITLE)[0]
lr.initialise_labels()

pcd_space = lr.get_space(id=SPACE_ID, type_="point_cloud")
print(pcd_space.metadata.stream_id, pcd_space.metadata.uri)

ontology = project.ontology_structure
# Point cloud objects must be a segmentation shape
ground: Object = ontology.get_child_by_title(title="Ground", type_=Object)
ground_inst: ObjectInstance = ground.create_instance()

# Option A: explicit point ranges
pcd_space.put_object_instance(
    ground_inst,
    [Range(start=0, end=5000)],
    on_overlap="replace",   # "error" (default) | "merge" | "replace"
)

# Option B: an Encord-compatible RLE string (segmentation shapes only)
# pcd_space.put_object_instance(ground_inst, "<encord_rle_string>")

lr.save()
```

<Info>
  `on_overlap` semantics differ by pattern: geometric and multi-frame spaces accept `"error"` (default) and `"replace"`; range and point cloud spaces additionally accept `"merge"` to add new ranges while keeping existing annotations.
</Info>


# Label Versions & Branches
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-label-versioning



Label branches let you keep multiple versions of a Project's labels side-by-side. Use them to preserve a labeled state before a re-labeling pass, run an experiment without disturbing `main`, or hold a reviewer-only copy of labels.

You create a new label version by copying labels from an existing branch onto a new branch with `project.copy_labels_to_branch()`. Every Project starts with a `main` branch. Copying from `main` (or any branch) into a new branch name creates that branch and populates it with the matching label rows.

<Tip>
  Label branches are the recommended method for **Pre-labeling Agents** and **Exporting Labels Agents**.

  * A **Pre-labeling Agent** writes its model predictions onto a dedicated branch (for example, `pre-labels-v1`) instead of `main`. Annotators continue working on `main` undisturbed, and you can review or merge the agent's output on its own branch with `copy_labels_to_branch(..., overwrite=True)` once it's been validated.

  * An **Exporting Labels Agent** copies the current state of `main` onto a frozen snapshot branch (for example, `export-2026-05-12`) before export. The export reads from that branch via `list_label_rows_v2(branch_name=...)`, so the result is reproducible even if annotation continues on `main` in parallel.
</Tip>

<CodeGroup>
  ```python Template theme={"dark"}
  project.copy_labels_to_branch(
      target_branch="<new-branch-name>",
      source_branch="main",
      overwrite=False,
      data_hashes=None,
      label_hashes=None,
      batch_size=50,
  )
  ```

  ```python Example theme={"dark"}
  project.copy_labels_to_branch(
      target_branch="pre-label-v1",
      source_branch="main",
  )
  ```
</CodeGroup>

The method returns the total number of label rows created or updated on the target branch.

<Warning>
  `source_branch` and `target_branch` MUST be different. Passing the same name for both raises a `ValueError`.
</Warning>

<Warning>
  By default, data units that already have a label row on `target_branch` are **skipped**. Set `overwrite=True` to replace existing label rows on the target branch with the source content.
</Warning>

<Note>
  All examples on this page use [`bundle`](/sdk-documentation/sdk-references/http.bundle#bundle-objects) when calling `initialise_labels()` or `save()` to reduce network round-trips. Keep bundle sizes **under 1000** operations — larger bundles can degrade performance. A good starting point is `BUNDLE_SIZE = 100`; for videos with many labels, start at `20` and adjust. `copy_labels_to_branch()` does not need a `bundle` — it batches internally via its own `batch_size` parameter (default `50`).
</Note>

<Warning>
  The examples below are intended as **quick tests** and cap themselves at the first `MAX_LABEL_ROWS = 10` label rows so you can validate the workflow safely. Remove that cap **deliberately** before running against a full Project — copying or overwriting labels on tens of thousands of rows without filtering can take a long time and is hard to undo.
</Warning>

## Copy All Labels to a New Branch

The following example creates a new label version named `pre-label-v1` by copying every label row on `main` into the new branch. This is the most common pattern: snapshot the current label state before making changes.

```python Copy all labels to a new branch theme={"dark"}
# Import dependencies
from encord import EncordUserClient

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 Project ID
TARGET_BRANCH = "pre-label-v1"  # Replace with the name of the new branch
BATCH_SIZE = 50  # Number of label rows copied per API request (server-side batching)
MAX_LABEL_ROWS = 10  # Quick-test cap. Remove or raise this for a full Project copy.

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",
)

project = user_client.get_project(PROJECT_ID)

# Pick the first MAX_LABEL_ROWS data units from the source branch.
# Metadata-only — no initialization needed, so no bundle required here.
source_rows = project.list_label_rows_v2(branch_name="main")
data_hashes = [row.data_hash for row in source_rows[:MAX_LABEL_ROWS]]

# copy_labels_to_branch batches internally; no bundle required here.
rows_copied = project.copy_labels_to_branch(
    target_branch=TARGET_BRANCH,
    source_branch="main",
    data_hashes=data_hashes,
    batch_size=BATCH_SIZE,
)

print(f"Copied {rows_copied} label rows from 'main' to '{TARGET_BRANCH}' (test run).")
```

## Copy Labels for Specific Data Units

To version labels for only a subset of your Project, pass the `data_hashes` (or `label_hashes`) you want to include. Everything outside that list stays untouched on the target branch.

When you need to discover the `label_hashes` first, fetch them with `list_label_rows_v2()` from the source branch. You only need to initialise label rows (with a `bundle`) when you intend to read their contents — for the hash-discovery step alone, the metadata returned by `list_label_rows_v2()` is enough.

<CodeGroup>
  ```python Filter by data hashes theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  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 Project ID
  TARGET_BRANCH = "subset-v1"  # Replace with the name of the new branch
  BATCH_SIZE = 50

  DATA_HASHES = [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222",
  ]  # Replace with the data hashes you want to copy

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  project = user_client.get_project(PROJECT_ID)

  rows_copied = project.copy_labels_to_branch(
      target_branch=TARGET_BRANCH,
      source_branch="main",
      data_hashes=DATA_HASHES,
      batch_size=BATCH_SIZE,
  )

  print(f"Copied {rows_copied} label rows for {len(DATA_HASHES)} data units to '{TARGET_BRANCH}'.")
  ```

  ```python Filter by label hashes theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  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 Project ID
  TARGET_BRANCH = "subset-v1"  # Replace with the name of the new branch
  BATCH_SIZE = 50
  MAX_LABEL_ROWS = 10  # Quick-test cap. Remove or raise this for a full Project copy.

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  project = user_client.get_project(PROJECT_ID)

  # Discover label hashes from the source branch. Metadata-only — no initialization
  # needed, so no bundle required here.
  source_rows = project.list_label_rows_v2(
      branch_name="main",
      data_title_like="cherries-%",  # Replace with your filter, or omit to list everything
  )
  label_hashes = [row.label_hash for row in source_rows if row.label_hash][:MAX_LABEL_ROWS]

  rows_copied = project.copy_labels_to_branch(
      target_branch=TARGET_BRANCH,
      source_branch="main",
      label_hashes=label_hashes,
      batch_size=BATCH_SIZE,
  )

  print(f"Copied {rows_copied} label rows to '{TARGET_BRANCH}' (test run).")
  ```
</CodeGroup>

<Warning>
  When both `data_hashes` and `label_hashes` are specified, `data_hashes` is applied first and `label_hashes` is applied to the result.
</Warning>

## Switch to a Branch and Read Labels

Once a branch exists, use `list_label_rows_v2()` with `branch_name` to fetch the label rows on that branch. Initialise each label row inside a `create_bundle()` context so all the download calls are batched into a single round-trip.

```python Read labels from a branch theme={"dark"}
# Import dependencies
from encord import EncordUserClient

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 Project ID
BRANCH_NAME = "pre-label-v1"  # Replace with the branch you want to read from
BUNDLE_SIZE = 100  # Keep bundle sizes under 1000 for best performance
MAX_LABEL_ROWS = 10  # Quick-test cap. Remove this slice to read every label row on the branch.

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    domain="https://api.encord.com",
)

project = user_client.get_project(PROJECT_ID)

# Fetch label rows for a specific branch, then cap at MAX_LABEL_ROWS for the test run.
label_rows = project.list_label_rows_v2(branch_name=BRANCH_NAME)[:MAX_LABEL_ROWS]

# Initialise labels using bundles to reduce network calls
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    print(f"{label_row.data_title}: {len(label_row.get_object_instances())} object instances on '{BRANCH_NAME}'")
```

<Warning>
  `branch_name` cannot be combined with `include_all_label_branches=True`. Pick one: either query a single branch by name, or pull every branch as separate label row objects.
</Warning>

To compare versions, list rows on each branch and inspect their contents. Bundle the initialization calls for each branch separately so each batch maps cleanly to one branch.

```python Compare two branches theme={"dark"}
# Import dependencies
from encord import EncordUserClient

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 Project ID
SOURCE_BRANCH = "main"
TARGET_BRANCH = "pre-label-v1"
BUNDLE_SIZE = 100
MAX_LABEL_ROWS = 10  # Quick-test cap. Remove this slice to compare every data unit.

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    domain="https://api.encord.com",
)

project = user_client.get_project(PROJECT_ID)

# Cap each branch at MAX_LABEL_ROWS for the test run.
source_rows = {
    r.data_hash: r
    for r in project.list_label_rows_v2(branch_name=SOURCE_BRANCH)[:MAX_LABEL_ROWS]
}
# Only compare data units that exist on both branches.
target_rows = {
    r.data_hash: r
    for r in project.list_label_rows_v2(
        branch_name=TARGET_BRANCH,
        data_hashes=list(source_rows.keys()),
    )
}

# Initialise the source branch in a single bundled request
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for row in source_rows.values():
        row.initialise_labels(bundle=bundle)

# Initialise the target branch in a single bundled request
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for row in target_rows.values():
        row.initialise_labels(bundle=bundle)

for data_hash, source_row in source_rows.items():
    target_row = target_rows.get(data_hash)
    if target_row is None:
        print(f"{source_row.data_title}: missing on '{TARGET_BRANCH}'")
        continue

    src_count = len(source_row.get_object_instances())
    tgt_count = len(target_row.get_object_instances())
    print(f"{source_row.data_title}: {SOURCE_BRANCH}={src_count}, {TARGET_BRANCH}={tgt_count}")
```

## Sync or Merge Branches

There is no dedicated "merge" call. To push updates from one branch back into another, call `copy_labels_to_branch()` again with `overwrite=True`. This replaces label rows on the target branch with the latest content from the source branch.

<Warning>
  `overwrite=True` is destructive. Label rows on the target branch are replaced with the source content for every matched data unit. There is no automatic conflict resolution — the source wins. Filter with `data_hashes` or `label_hashes` if you want to limit the sync.
</Warning>

<CodeGroup>
  ```python Sync changes from a branch back to main theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  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 Project ID
  SOURCE_BRANCH = "pre-label-v1"  # Branch with the updated labels
  TARGET_BRANCH = "main"  # Branch to update
  BATCH_SIZE = 50
  MAX_LABEL_ROWS = 10  # Quick-test cap. Remove this slice to sync every data unit on the source branch.

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  project = user_client.get_project(PROJECT_ID)

  # Pick the first MAX_LABEL_ROWS data units from the source branch to sync back.
  source_rows = project.list_label_rows_v2(branch_name=SOURCE_BRANCH)
  data_hashes = [row.data_hash for row in source_rows[:MAX_LABEL_ROWS]]

  rows_synced = project.copy_labels_to_branch(
      target_branch=TARGET_BRANCH,
      source_branch=SOURCE_BRANCH,
      overwrite=True,
      data_hashes=data_hashes,
      batch_size=BATCH_SIZE,
  )

  print(f"Synced {rows_synced} label rows from '{SOURCE_BRANCH}' to '{TARGET_BRANCH}' (test run).")
  ```

  ```python Sync only specific data units theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  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 Project ID
  SOURCE_BRANCH = "pre-label-v1"
  TARGET_BRANCH = "main"
  BATCH_SIZE = 50

  DATA_HASHES_TO_MERGE = [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222",
  ]  # Replace with the data units to merge back

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  project = user_client.get_project(PROJECT_ID)

  rows_synced = project.copy_labels_to_branch(
      target_branch=TARGET_BRANCH,
      source_branch=SOURCE_BRANCH,
      overwrite=True,
      data_hashes=DATA_HASHES_TO_MERGE,
      batch_size=BATCH_SIZE,
  )

  print(f"Merged {rows_synced} label rows from '{SOURCE_BRANCH}' into '{TARGET_BRANCH}'.")
  ```

  ```python Read, edit, and save back to a branch theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient

  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 Project ID
  BRANCH_NAME = "pre-label-v1"
  BUNDLE_SIZE = 100
  MAX_LABEL_ROWS = 10  # Quick-test cap. Remove this slice to edit every label row on the branch.

  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH,
      domain="https://api.encord.com",
  )

  project = user_client.get_project(PROJECT_ID)
  label_rows = project.list_label_rows_v2(branch_name=BRANCH_NAME)[:MAX_LABEL_ROWS]

  # Bundle the reads
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.initialise_labels(bundle=bundle)

  # Perform any edits on label_rows here.

  # Bundle the writes back to the branch
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows:
          label_row.save(bundle=bundle)

  print(f"Saved {len(label_rows)} label rows on '{BRANCH_NAME}' (test run).")
  ```
</CodeGroup>

After copying, verify the result by listing label rows on the target branch:

```python Verify the copy theme={"dark"}
verification_rows = project.list_label_rows_v2(branch_name="pre-label-v1")
print(f"'pre-label-v1' now contains {len(verification_rows)} label rows.")
```


# HTML
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-labels-html



## Import Text Regions to HTML

A single `text region` object label can be added at a time between `start` and `end` using `range`.

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from typing import List
  from encord import EncordUserClient
  from encord.objects import LabelRowV2, Object, ObjectInstance, OntologyStructure
  from encord.objects.coordinates import HtmlCoordinates
  from encord.objects.html_node import HtmlRange, HtmlNode

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

  # Instantiate Encord client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify the project
  project = user_client.get_project(PROJECT_ID)

  label_row = project.list_label_rows_v2(
      data_title_eq="<file-name-of-html-file>"
  )[0]

  label_row.initialise_labels()

  range_html = HtmlRange(
      start=HtmlNode(
         xpath="<full-XPath>",
          offset=<location-of-text-or-object>
      ),
      end=HtmlNode(
         xpath="<full-XPath>",
          offset=<location-of-text-or-object>
      )
  )

  html_object: Object = project.ontology_structure.get_child_by_title(
          title="<text-region-name>", type_=Object
      )

  html_object_instance: ObjectInstance = html_object.create_instance()

  # `frames=0` is an optional. It indicates that the text file is a single data unit.

  html_object_instance.set_for_frames(frames=0, coordinates=HtmlCoordinates(range=[range_html]))

  label_row.add_object_instance(html_object_instance)
  label_row.save()

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from typing import List
  from encord import EncordUserClient
  from encord.objects import LabelRowV2, Object, ObjectInstance, OntologyStructure
  from encord.objects.coordinates import HtmlCoordinates
  from encord.objects.html_node import HtmlRange, HtmlNode

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID = "7b345a15-5f76-4a12-961b-2b1f2vv932bb"

  # Instantiate Encord client
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify the project
  project = user_client.get_project(PROJECT_ID)

  label_row = project.list_label_rows_v2(
      data_title_eq="My HTML Page.html"
  )[0]

  label_row.initialise_labels()

  range_html = HtmlRange(
      start=HtmlNode(
         xpath="/html/body/div[1]/main/div/div[2]/div[2]/div/div[1]/div[2]/p[3]",
          offset=30
      ),
      end=HtmlNode(
         xpath="/html/body/div[1]/main/div/div[2]/div[2]/div/div[1]/div[2]/p[3]",
          offset=40
      )
  )

  html_object: Object = project.ontology_structure.get_child_by_title(
          title="Text Region - HTML", type_=Object
      )

  html_object_instance: ObjectInstance = html_object.create_instance()

  # `frames=0` is an optional. It indicates that the text file is a single data unit.

  html_object_instance.set_for_frames(frames=0, coordinates=HtmlCoordinates(range=[range_html]))

  label_row.add_object_instance(html_object_instance)
  label_row.save()

  ```
</CodeGroup>

## Import Classifications to HTML

The example for the Classification uses nested attributes with the Ontology structure as follows:

* Accurate?
  * Yes
  * No
    * Correction (text field to provide edits for the correction)

<Note>`create_instance` must use `range_only=True` for text documents. This includes HTML documents.</Note>

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from typing import List
  from pathlib import Path
  from encord import EncordUserClient, Project
  from encord.objects import LabelRowV2, Classification, Option, OntologyStructure

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

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

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

  # Specify the data unit to apply classification
  label_row = project.list_label_rows_v2(
      data_title_eq="<file-name-for-html-file>.html"
  )[0]


  # Download the existing labels 
  label_row.initialise_labels()

  # Get the Ontology structure
  ontology_structure: OntologyStructure = label_row.ontology_structure

  # Assume that the following radio button classification exists in the Ontology.
  radio_ontology_classification: Classification = (
      ontology_structure.get_child_by_title(
          title="<classification-name>", type_=Classification
      )
  )

  radio_classification_option = radio_ontology_classification.get_child_by_title(
  title="<option-name>",
  type_=Option
  )

  # Create classification instance. `range_only=True` is required for HTML documents
  radio_classification_instance = radio_ontology_classification.create_instance(range_only=True)

  # Set the answer of the classification instance
  radio_classification_instance.set_answer(radio_classification_option)

  # Select the frames where the classification instance is present. Not required for global classifications
  radio_classification_instance.set_for_frames(frames=0)

  # Add it to the label row
  label_row.add_classification_instance(radio_classification_instance)

  # Save labels
  label_row.save()

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from __future__ import annotations
  from pathlib import Path
  from encord import EncordUserClient, Project
  from encord.objects import (
      Classification,
      OntologyStructure,
      LabelRowV2,
      TextAttribute,
      RadioAttribute,
      Option
  )
  from encord.objects.html_node import HtmlRange, HtmlNode

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID = "8a321a14-5f76-4a12-961b-3b1f2da932gk"

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

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

  # Specify the data unit to apply classification
  label_row = project.list_label_rows_v2(
      data_title_eq="My HTML Page.html"
  )[0]

  label_row.initialise_labels()

  ontology_structure: OntologyStructure = label_row.ontology_structure

  # Get the parent classification
  text_ontology_classification = ontology_structure.get_child_by_title(
      title="Accurate?", type_=Classification
  )

  # Create an instance of the radio button classification
  text_classification_instance = text_ontology_classification.create_instance(range_only=True)

  # Get the radio button attribute and option
  accurate_radio_attribute = text_ontology_classification.get_child_by_title("Accurate?", type_=RadioAttribute)
  not_accurate_option = text_ontology_classification.get_child_by_title(title="No", type_=Option)

  # Set the answer for the radio button
  text_classification_instance.set_answer(attribute=accurate_radio_attribute, answer=not_accurate_option)

  # Get the nested attribute "Correction"
  correction_attribute = text_ontology_classification.get_child_by_title("Correction", type_=TextAttribute)

  # Set the text for the nested attribute
  text_classification_instance.set_answer(attribute=correction_attribute, answer="This page needs to be updated.")

  # Set the classification (for text documents) for use with the entire file
  text_classification_instance.set_for_frames(frames=0)

  # Add the classification instance to the label row
  label_row.add_classification_instance(text_classification_instance)

  # Save the label row
  label_row.save()

  ```
</CodeGroup>

## Export Labels for HTML Files

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  import json

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

  # Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]

  # Download label information for the specific data unit
  specific_label_row.initialise_labels()

  # Print the labels as JSON
  print(json.dumps(specific_label_row.to_encord_dict()))

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  import json

  SSH_PATH= "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID= "7a321a15-5f76-4a12-961b-2b1f2da932bb"
  DATA_UNIT_NAME= "My HTML Page.html"

  # Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]

  # Download label information for the specific data unit
  specific_label_row.initialise_labels()

  # Print the labels as JSON
  print(json.dumps(specific_label_row.to_encord_dict()))

  ```
</CodeGroup>

## Remove Labels from HTML Files

<CodeGroup>
  ```python Template theme={"dark"}

  from encord import EncordUserClient
  import json

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

  # Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]


  object_to_remove = None
  specific_label_row.initialise_labels()
  for object_instance in specific_label_row.get_object_instances():
      if object_instance.object_hash == '<label-unique-id>':
          object_to_remove = object_instance

  specific_label_row.remove_object(object_to_remove)

  specific_label_row.save()

  ```

  ```python Example theme={"dark"}

  from encord import EncordUserClient
  import json

  SSH_PATH= "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID= "7v321a15-5f76-4a12-961b-2b1f2da932bb"
  DATA_UNIT_NAME= "My HTML Page.html"

  # Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]


  object_to_remove = None
  specific_label_row.initialise_labels()
  for object_instance in specific_label_row.get_object_instances():
      if object_instance.object_hash == 'dH3DrglO':
          object_to_remove = object_instance

  specific_label_row.remove_object(object_to_remove)

  specific_label_row.save()

  ```
</CodeGroup>


# Point Cloud (3D)
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-labels-import-3d



## Cuboids

**Basic**

This example includes the following:

* Cuboid labeling

**Advanced**

This example includes the following:

* Cuboid labeling
* Radio button options
* Checklist options
* Text input

**Cuboid Ontology**

![Cuboid Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/ontology-pcd-cuboids.png)

<CodeGroup>
  ```python Cuboids - Basic expandable theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient, Project
  from encord.objects import Object
  from encord.objects.coordinates import CuboidCoordinates

  # 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 cuboid annotation object in the project ontology
  cuboid_ontology_object: Object = ontology_structure.get_child_by_title(title="Person", type_=Object)
  assert cuboid_ontology_object is not None, "Cuboid object 'Person' not found in ontology."

  # Dictionary of labels per data unit and per frame with Person
  pcd_labels = {
      "scene-1094": {
          0: {
              "label_ref": "person_001",
              "coordinates": CuboidCoordinates(
                  position=(9, 9, 9), 
                  orientation=(0.11, 0.77, 0.33), 
                  size=(0.2, 0.2, 0.2)
                  ),
          }
      },
      "scene-0916": {
          0: [
              {
                  "label_ref": "person_002",
                  "coordinates": CuboidCoordinates(
                      position=(0.4, 0.4, 0.4), 
                      orientation=(0.0, 0.0, 0.4), 
                      size=(0.1, 0.1, 0.1)
                  ),
              },
              {
                  "label_ref": "person_003",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.1), 
                      size=(0.5, 0.5, 0.5)
                  ),
              },
              {
                  "label_ref": "person_004",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.1), 
                      size=(0.7, 0.7, 0.7)
                  ),
              },
          ],
      },
      "scene-0796": {
          0: {
              "label_ref": "person_005",
              "coordinates": CuboidCoordinates(
                  position=(0.4, 0.4, 0.0), 
                  orientation=(0.0, 0.0, 0.4), 
                  size=(0.12, 0.12, 0.12)
              ),
          },
          2: [
              {
                  "label_ref": "person_006",
                  "coordinates": CuboidCoordinates(
                      position=(0.1, 0.1, 0.0), 
                      orientation=(0.0, 0.0, 0.2), 
                      size=(0.5, 0.5, 0.5)
                  ),
              },
              {
                  "label_ref": "person_007",
                  "coordinates": CuboidCoordinates(
                      position=(0.1, 0.1, 0.0), 
                      orientation=(0.0, 0.0, 0.2), 
                      size=(0.0132, 0.0132, 0.0132)
                  ),
              },
              {
                  "label_ref": "person_008",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.1), 
                      size=(0.8, 0.8, 0.8)
                  ),
              },
          ],
      },
      "scene-1100": {
          0: {
              "label_ref": "person_009",
              "coordinates": CuboidCoordinates(
                  position=(0.4, 0.4, 0.0), 
                  orientation=(0.0, 0.0, 0.4), 
                  size=(0.012, 0.012, 0.012)
              ),
          },
          3: [
              {
                  "label_ref": "person_010",
                  "coordinates": CuboidCoordinates(
                      position=(0.4, 0.4, 0.0), 
                      orientation=(0.0, 0.0, 0.4), 
                      size=(0.5, 0.5, 0.5)
                  ),
              },
              {
                  "label_ref": "person_011",
                  "coordinates": CuboidCoordinates(
                      position=(0.3, 0.3, 0.0), 
                      orientation=(0.0, 0.0, 0.3), 
                      size=(0.13, 0.13, 0.13)
                  ),
              },
              {
                  "label_ref": "person_012",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.1), 
                      size=(0.9, 0.9, 0.9)
                  ),
              },
          ],
      },
      "scene-0655": {
          13: [
              {
                  "label_ref": "person_013",
                  "coordinates": CuboidCoordinates(
                      position=(0.5, 0.5, 0.0), 
                      orientation=(0.0, 0.0, 0.5), 
                      size=(0.11, 0.11, 0.11)
                  ),
              },
              {
                  "label_ref": "person_014",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.2), 
                      size=(0.6, 0.6, 0.6)
                  ),
              },
              {
                  "label_ref": "person_015",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.1), 
                      size=(0.8, 0.8, 0.8)
                  ),
              },
          ],
          14: [
              {
                  "label_ref": "person_016",
                  "coordinates": CuboidCoordinates(
                      position=(0.5, 0.5, 0.0), 
                      orientation=(0.0, 0.0, 0.5), 
                      size=(0.3, 0.3, 0.3)
                  ),
              },
              {
                  "label_ref": "person_014",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.2), 
                      size=(0.6, 0.6, 0.6)
                  ),
              },
              {
                  "label_ref": "person_017",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.1), 
                      size=(0.8, 0.8, 0.8)
                  ),
              },
          ],
          15: [
              {
                  "label_ref": "person_016",
                  "coordinates": CuboidCoordinates(
                      position=(0.5, 0.5, 0.0), 
                      orientation=(0.0, 0.0, 0.5), 
                      size=(0.1, 0.1, 0.1)
                  ),
              },
              {
                  "label_ref": "person_014",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.2), 
                      size=(0.6, 0.6, 0.6)
                  ),
              },
              {
                  "label_ref": "person_017",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), 
                      orientation=(0.0, 0.0, 0.1), 
                      size=(0.8, 0.8, 0.8)
                  ),
              },
          ],
      },
  }


  # Initialize label rows
  label_row_map = {}
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_title in pcd_labels.keys():
          rows = project.list_label_rows_v2(data_title_eq=data_title)
          if not rows:
              print(f"Skipping: No label row found for {data_title}")
              continue
          lr = rows[0]
          lr.initialise_labels(bundle=bundle)
          label_row_map[data_title] = lr

  # Create instances
  label_rows_to_save = []
  for data_title, frames in pcd_labels.items():
      lr = label_row_map.get(data_title)
      if not lr:
          continue

      instances_by_ref = {}

      for frame_no, items in frames.items():
          # normalize to list
          items = items if isinstance(items, list) else [items]

          for item in items:
              ref = item["label_ref"]
              coords = item["coordinates"]

              if ref not in instances_by_ref:
                  instances_by_ref[ref] = cuboid_ontology_object.create_instance()

              instances_by_ref[ref].set_for_frames(coordinates=coords, frames=frame_no)

      # Add only instances that have at least one frame
      for inst in instances_by_ref.values():
          if inst.get_annotation_frames():
              lr.add_object_instance(inst)

      label_rows_to_save.append(lr)

  # Save all label rows
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for lr in label_rows_to_save:
          lr.save(bundle=bundle)
          print(f"Saved label row for {lr.data_title}")
  ```

  ```python Cuboids - Advanced expandable theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient, Project
  from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
  from encord.objects.attributes import NumericAttribute
  from encord.objects.coordinates import CuboidCoordinates

  # 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 cuboid annotation object in the project ontology
  cuboid_ontology_object: Object = ontology_structure.get_child_by_title(title="Person", type_=Object)
  assert cuboid_ontology_object is not None, "Cuboid object 'Person' not found in ontology."

  person_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
  assert person_type_radio_attribute is not None, "Radio attribute 'Type?' not found in ontology."

  # Create options for the radio buttons
  adult_option = person_type_radio_attribute.get_child_by_title(type_=Option, title="Adult")
  adolescent_option = person_type_radio_attribute.get_child_by_title(type_=Option, title="Adolescent")
  child_option = person_type_radio_attribute.get_child_by_title(type_=Option, title="Child")
  other_person_option = person_type_radio_attribute.get_child_by_title(type_=Option, title="Other Person type")

  assert all([adult_option, adolescent_option, child_option, other_person_option]), (
      "One or more Person type options are missing."
  )

  # Adult Qualities
  adult_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Adult Qualities?")
  assert adult_checklist_attribute is not None, "Checklist attribute 'Adult Qualities?' not found."

  adult_moving_option = adult_checklist_attribute.get_child_by_title(type_=Option, title="Moving")
  adult_well_lit_option = adult_checklist_attribute.get_child_by_title(type_=Option, title="Well lit")
  adult_fully_visible_option = adult_checklist_attribute.get_child_by_title(type_=Option, title="Fully visible")
  assert all([adult_moving_option, adult_well_lit_option, adult_fully_visible_option]), (
      "One or more Adult quality options are missing."
  )

  # Adolescent Qualities
  adolescent_checklist_attribute = ontology_structure.get_child_by_title(
      type_=ChecklistAttribute, title="Adolescent Qualities?"
  )
  assert adolescent_checklist_attribute is not None, "Checklist attribute 'Adolescent Qualities?' not found."

  adolescent_moving_option = adolescent_checklist_attribute.get_child_by_title(type_=Option, title="Moving")
  adolescent_well_lit_option = adolescent_checklist_attribute.get_child_by_title(type_=Option, title="Well lit")
  adolescent_fully_visible_option = adolescent_checklist_attribute.get_child_by_title(type_=Option, title="Fully visible")
  assert all([adolescent_moving_option, adolescent_well_lit_option, adolescent_fully_visible_option]), (
      "One or more Adolescent quality options are missing."
  )

  # Child Qualities
  child_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Child Qualities?")
  assert child_checklist_attribute is not None, "Checklist attribute 'Child Qualities?' not found."

  child_moving_option = child_checklist_attribute.get_child_by_title(type_=Option, title="Moving")
  child_well_lit_option = child_checklist_attribute.get_child_by_title(type_=Option, title="Well lit")
  child_fully_visible_option = child_checklist_attribute.get_child_by_title(type_=Option, title="Fully visible")
  assert all([child_moving_option, child_well_lit_option, child_fully_visible_option]), (
      "One or more Child quality options are missing."
  )

  # Other Person Types
  other_person_option_text_attribute = ontology_structure.get_child_by_title(
      type_=TextAttribute, title="Specify Person type"
  )
  assert other_person_option_text_attribute is not None, "Text attribute 'Specify Person type' not found in ontology."

  # Dictionary of labels per data unit and per frame with Person type specified, including quality options
  pcd_labels = {
      "scene-1094": {
          0: {
              "label_ref": "person_001",
              "coordinates": CuboidCoordinates(position=(9, 9, 9), orientation=(0.11, 0.77, 0.33), size=(0.2, 0.2, 0.2)),
              "person_type": "Adult",
              "adult_quality_options": "Moving, Well lit",
          }
      },
      "scene-0916": {
          0: [
              {
                  "label_ref": "person_002",
                  "coordinates": CuboidCoordinates(
                      position=(0.4, 0.4, 0.4), orientation=(0.0, 0.0, 0.4), size=(0.1, 0.1, 0.1)
                  ),
                  "person_type": "Adolescent",
                  "adolescent_quality_options": "Moving, Well lit, Fully visible",
              },
              {
                  "label_ref": "person_003",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.1), size=(0.5, 0.5, 0.5)
                  ),
                  "person_type": "Child",
                  "child_quality_options": "Moving",
              },
              {
                  "label_ref": "person_004",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.1), size=(0.7, 0.7, 0.7)
                  ),
                  "person_type": "Other Person type",
                  "Specify Person type": "Person with a baby stroller",
              },
          ],
      },
      "scene-0796": {
          0: {
              "label_ref": "person_005",
              "coordinates": CuboidCoordinates(
                  position=(0.4, 0.4, 0.0), orientation=(0.0, 0.0, 0.4), size=(0.12, 0.12, 0.12)
              ),
              "person_type": "Adult",
              "adult_quality_options": "Moving, Well lit",
          },
          2: [
              {
                  "label_ref": "person_006",
                  "coordinates": CuboidCoordinates(
                      position=(0.1, 0.1, 0.0), orientation=(0.0, 0.0, 0.2), size=(0.5, 0.5, 0.5)
                  ),
                  "person_type": "Adolescent",
                  "adolescent_quality_options": "Fully visible",
              },
              {
                  "label_ref": "person_007",
                  "coordinates": CuboidCoordinates(
                      position=(0.1, 0.1, 0.0), orientation=(0.0, 0.0, 0.2), size=(0.0132, 0.0132, 0.0132)
                  ),
                  "person_type": "Child",
                  "child_quality_options": "Moving",
              },
              {
                  "label_ref": "person_008",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.1), size=(0.8, 0.8, 0.8)
                  ),
                  "person_type": "Other Person type",
                  "Specify Person type": "Person with a baby stroller",
              },
          ],
      },
      "scene-1100": {
          0: {
              "label_ref": "person_009",
              "coordinates": CuboidCoordinates(
                  position=(0.4, 0.4, 0.0), orientation=(0.0, 0.0, 0.4), size=(0.012, 0.012, 0.012)
              ),
              "person_type": "Adult",
              "adult_quality_options": "Moving",
          },
          3: [
              {
                  "label_ref": "person_010",
                  "coordinates": CuboidCoordinates(
                      position=(0.4, 0.4, 0.0), orientation=(0.0, 0.0, 0.4), size=(0.5, 0.5, 0.5)
                  ),
                  "person_type": "Adolescent",
                  "adolescent_quality_options": "Moving, Well lit, Fully visible",
              },
              {
                  "label_ref": "person_011",
                  "coordinates": CuboidCoordinates(
                      position=(0.3, 0.3, 0.0), orientation=(0.0, 0.0, 0.3), size=(0.13, 0.13, 0.13)
                  ),
                  "person_type": "Child",
                  "child_quality_options": "Moving",
              },
              {
                  "label_ref": "person_012",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.1), size=(0.9, 0.9, 0.9)
                  ),
                  "person_type": "Other Person type",
                  "Specify Person type": "Person with a baby stroller",
              },
          ],
      },
      "scene-0655": {
          13: [
              {
                  "label_ref": "person_013",
                  "coordinates": CuboidCoordinates(
                      position=(0.5, 0.5, 0.0), orientation=(0.0, 0.0, 0.5), size=(0.11, 0.11, 0.11)
                  ),
                  "person_type": "Child",
                  "child_quality_options": "Moving",
              },
              {
                  "label_ref": "person_014",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.2), size=(0.6, 0.6, 0.6)
                  ),
                  "person_type": "Adult",
                  "adult_quality_options": "Moving, Well lit, Fully visible",
              },
              {
                  "label_ref": "person_015",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.1), size=(0.8, 0.8, 0.8)
                  ),
                  "person_type": "Other Person type",
                  "Specify Person type": "Person walking a dog",
              },
          ],
          14: [
              {
                  "label_ref": "person_016",
                  "coordinates": CuboidCoordinates(
                      position=(0.5, 0.5, 0.0), orientation=(0.0, 0.0, 0.5), size=(0.3, 0.3, 0.3)
                  ),
                  "person_type": "Child",
                  "child_quality_options": "Moving",
              },
              {
                  "label_ref": "person_014",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.2), size=(0.6, 0.6, 0.6)
                  ),
                  "person_type": "Adult",
                  "adult_quality_options": "Moving, Well lit, Fully visible",
              },
              {
                  "label_ref": "person_017",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.1), size=(0.8, 0.8, 0.8)
                  ),
                  "person_type": "Other Person type",
                  "Specify Person type": "Person walking a dog",
              },
          ],
          15: [
              {
                  "label_ref": "person_016",
                  "coordinates": CuboidCoordinates(
                      position=(0.5, 0.5, 0.0), orientation=(0.0, 0.0, 0.5), size=(0.1, 0.1, 0.1)
                  ),
                  "person_type": "Child",
                  "child_quality_options": "Moving",
              },
              {
                  "label_ref": "person_014",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.2), size=(0.6, 0.6, 0.6)
                  ),
                  "person_type": "Adult",
                  "adult_quality_options": "Moving, Well lit, Fully visible",
              },
              {
                  "label_ref": "person_017",
                  "coordinates": CuboidCoordinates(
                      position=(0.2, 0.2, 0.0), orientation=(0.0, 0.0, 0.1), size=(0.8, 0.8, 0.8)
                  ),
                  "person_type": "Other Person type",
                  "Specify Person type": "Person walking a dog",
              },
          ],
      },
  }


  # Cache initialized label rows
  label_row_map = {}

  # Step 1: Initialize all label rows using a bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_unit in pcd_labels.keys():
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"

          if not label_rows:
              print(f"Skipping: No label row found for {data_unit}")
              continue

          label_row = label_rows[0]
          label_row.initialise_labels(bundle=bundle)
          assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

          label_row_map[data_unit] = label_row  # Cache initialized label row for later use

  # Step 2: Process all frames/annotations and prepare label rows to save
  label_rows_to_save = []

  for data_unit, frame_coordinates in pcd_labels.items():
      label_row = label_row_map.get(data_unit)
      if not label_row:
          print(f"Skipping: No initialized label row found for {data_unit}")
          continue

      object_instances_by_label_ref = {}

      # Loop through the frames for the current data unit
      for frame_number, items in frame_coordinates.items():
          assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"
          if not isinstance(items, list):
              items = [items]

          for item in items:
              label_ref = item["label_ref"]
              coord = item["coordinates"]
              person_type = item["person_type"]

              assert person_type in {
                  "Adult",
                  "Adolescent",
                  "Child",
                  "Other Person type",
              }, f"Unexpected Person type '{person_type}' in data unit '{data_unit}'"

              # Check if label_ref already exists for reusability
              if label_ref not in object_instances_by_label_ref:
                  cuboid_object_instance: ObjectInstance = cuboid_ontology_object.create_instance()
                  assert cuboid_object_instance is not None, "Failed to create ObjectInstance"

                  object_instances_by_label_ref[label_ref] = cuboid_object_instance
                  checklist_attribute = None

                  # Set Person type attribute
                  if person_type == "Adult":
                      assert adult_option is not None, "Missing 'adult_option'"
                      cuboid_object_instance.set_answer(attribute=person_type_radio_attribute, answer=adult_option)
                      checklist_attribute = adult_checklist_attribute
                  elif person_type == "Adolescent":
                      assert adolescent_option is not None, "Missing 'adolescent_option'"
                      cuboid_object_instance.set_answer(attribute=person_type_radio_attribute, answer=adolescent_option)
                      checklist_attribute = adolescent_checklist_attribute
                  elif person_type == "Child":
                      assert child_option is not None, "Missing 'child_option'"
                      cuboid_object_instance.set_answer(attribute=person_type_radio_attribute, answer=child_option)
                      checklist_attribute = child_checklist_attribute
                  elif person_type == "Other Person type":
                      assert other_person_option is not None, "Missing 'other_person_option'"
                      cuboid_object_instance.set_answer(attribute=person_type_radio_attribute, answer=other_person_option)
                      text_answer = item.get("Specify Person type", "")
                      assert isinstance(text_answer, str), "'Specify Person type' must be a string"
                      cuboid_object_instance.set_answer(attribute=other_person_option_text_attribute, answer=text_answer)

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

                  for quality in quality_options:
                      if quality == "Moving":
                          checklist_answers.append(
                              adult_moving_option
                              if person_type == "Adult"
                              else adolescent_moving_option
                              if person_type == "Adolescent"
                              else child_moving_option
                          )
                      elif quality == "Well lit":
                          checklist_answers.append(
                              adult_well_lit_option
                              if person_type == "Adult"
                              else adolescent_well_lit_option
                              if person_type == "Adolescent"
                              else child_well_lit_option
                          )
                      elif quality == "Fully visible":
                          checklist_answers.append(
                              adult_fully_visible_option
                              if person_type == "Adult"
                              else adolescent_fully_visible_option
                              if person_type == "Adolescent"
                              else child_fully_visible_option
                          )

                  if checklist_attribute and checklist_answers:
                      cuboid_object_instance.set_answer(
                          attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                      )

              else:
                  # Reuse existing instance across frames
                  cuboid_object_instance = object_instances_by_label_ref[label_ref]

              # Assign the object to the frame and track it
              cuboid_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

      # Add object instances to label_row **only if they have frames assigned**
      for cuboid_object_instance in object_instances_by_label_ref.values():
          assert isinstance(cuboid_object_instance, ObjectInstance), "Expected ObjectInstance type"
          if cuboid_object_instance.get_annotation_frames():  # Ensures it has at least one frame
              label_row.add_object_instance(cuboid_object_instance)

      label_rows_to_save.append(label_row)

  # Step 3: Save all label rows using a bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows_to_save:
          assert label_row is not None, "Trying to save a None label row"
          label_row.save(bundle=bundle)
          print(f"Saved label row for {label_row.data_title}")

  print("Labels with Person type radio buttons, checklist attributes, and text labels added for all data units.")
  ```
</CodeGroup>

## Polylines 3D

**Basic**

This example includes the following:

* Polyline 3D labeling

**Advanced**

This example includes the following:

* Polyline 3D labeling
* Radio button options
* Checklist options
* Text input

**Polyline Ontology**

![Polyline 3D Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/ontology-pcd-polylines.png)

<CodeGroup>
  ```python 3D Polylines - Basic expandable theme={"dark"}

  # Import dependencies

  from encord import EncordUserClient, Project
  from encord.objects import Object
  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)

  # Get the ontology
  ontology_structure = project.ontology_structure

  # Find a polyline annotation object in the project ontology
  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."

  # Dictionary of labels per data unit and per frame with Object of Interest
  pcd_labels = {
      "scene-1094": {
          0: {
              "label_ref": "ooi_001",
              "coordinates": PolylineCoordinates(
                  [
                      PointCoordinate3D(2.013, 2.02, 2.015),
                      PointCoordinate3D(3.033, 3.033, 3.033),
                      PointCoordinate3D(4.053, 4.023, 4.017),
                      PointCoordinate3D(0.043, 0.013, 0.043),
                  ]
              ),
          }
      },
      "scene-0916": {
          0: [
              {
                  "label_ref": "ooi_002",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(3.000, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 3.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_003",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.300, 5.300, 0.000),
                          PointCoordinate3D(6.300, 6.300, 0.000),
                          PointCoordinate3D(8.300, 5.300, 0.000),
                          PointCoordinate3D(7.300, 4.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_004",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
              },
          ],
      },
      "scene-0796": {
          0: {
              "label_ref": "ooi_005",
              "coordinates": PolylineCoordinates(
                  [
                      PointCoordinate3D(1.300, 2.300, 0.000),
                      PointCoordinate3D(3.300, 3.300, 0.000),
                      PointCoordinate3D(5.300, 2.300, 0.000),
                      PointCoordinate3D(4.300, 1.300, 0.000),
                  ]
              ),
          },
          2: [
              {
                  "label_ref": "ooi_006",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.300, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 2.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_007",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.300, 5.300, 0.000),
                          PointCoordinate3D(6.300, 6.300, 0.000),
                          PointCoordinate3D(8.300, 5.300, 0.000),
                          PointCoordinate3D(7.300, 4.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_008",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
              },
          ],
      },
      "scene-1100": {
          0: {
              "label_ref": "ooi_009",
              "coordinates": PolylineCoordinates(
                  [
                      PointCoordinate3D(1.300, 2.300, 0.000),
                      PointCoordinate3D(3.300, 3.300, 0.000),
                      PointCoordinate3D(5.300, 2.300, 0.000),
                      PointCoordinate3D(4.300, 1.300, 0.000),
                  ]
              ),
          },
          3: [
              {
                  "label_ref": "ooi_010",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.300, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 2.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_011",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.300, 5.300, 0.000),
                          PointCoordinate3D(6.300, 6.300, 0.000),
                          PointCoordinate3D(8.300, 5.300, 0.000),
                          PointCoordinate3D(7.300, 4.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_012",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
              },
          ],
      },
      "scene-0655": {
          103: [
              {
                  "label_ref": "ooi_013",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.300, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 2.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_014",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.300, 5.300, 0.000),
                          PointCoordinate3D(6.300, 6.300, 0.000),
                          PointCoordinate3D(8.300, 5.300, 0.000),
                          PointCoordinate3D(7.300, 4.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_015",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
              },
          ],
          104: [
              {
                  "label_ref": "ooi_016",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.300, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 2.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_014",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.130, 5.230, 0.000),
                          PointCoordinate3D(6.130, 6.230, 0.000),
                          PointCoordinate3D(8.130, 5.230, 0.000),
                          PointCoordinate3D(7.130, 4.230, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_017",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
              },
          ],
          105: [
              {
                  "label_ref": "ooi_016",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.130, 2.230, 0.000),
                          PointCoordinate3D(3.130, 3.230, 0.000),
                          PointCoordinate3D(5.130, 2.230, 0.000),
                          PointCoordinate3D(4.130, 1.230, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_014",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.330, 5.530, 0.000),
                          PointCoordinate3D(6.330, 6.530, 0.000),
                          PointCoordinate3D(8.330, 5.530, 0.000),
                          PointCoordinate3D(7.330, 4.530, 0.000),
                      ]
                  ),
              },
              {
                  "label_ref": "ooi_017",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.130, 2.230, 0.000),
                          PointCoordinate3D(9.130, 3.230, 0.000),
                          PointCoordinate3D(11.130, 2.230, 0.000),
                          PointCoordinate3D(10.130, 1.230, 0.000),
                      ]
                  ),
              },
          ],
      },
  }

  # Initialize label rows
  label_row_map = {}
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_title in pcd_labels.keys():
          rows = project.list_label_rows_v2(data_title_eq=data_title)
          if not rows:
              print(f"Skipping: No label row found for {data_title}")
              continue
          lr = rows[0]
          lr.initialise_labels(bundle=bundle)
          label_row_map[data_title] = lr

  # Create instances
  label_rows_to_save = []
  for data_title, frames in pcd_labels.items():
      lr = label_row_map.get(data_title)
      if not lr:
          continue

      instances_by_ref = {}

      for frame_no, items in frames.items():
          # normalize to list
          items = items if isinstance(items, list) else [items]

          for item in items:
              ref = item["label_ref"]
              coords = item["coordinates"]

              if ref not in instances_by_ref:
                  instances_by_ref[ref] = polyline_ontology_object.create_instance()

              instances_by_ref[ref].set_for_frames(coordinates=coords, frames=frame_no)

      # Add only instances that have at least one frame
      for inst in instances_by_ref.values():
          if inst.get_annotation_frames():
              lr.add_object_instance(inst)

      label_rows_to_save.append(lr)

  # Save all label rows
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for lr in label_rows_to_save:
          lr.save(bundle=bundle)
          print(f"Saved label row for {lr.data_title}")
  ```

  ```python 3D Polylines - Advanced expandable theme={"dark"}

  # 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"

  # Get radio attribute for Object of Interest type
  ooi_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
  assert ooi_type_radio_attribute is not None, "Radio attribute 'Type?' not found in ontology"

  # Get radio options
  curb_option = ooi_type_radio_attribute.get_child_by_title(type_=Option, title="Curb")
  assert curb_option is not None, "Option 'Curb' not found under radio attribute 'Type?'"

  lane_divider_option = ooi_type_radio_attribute.get_child_by_title(type_=Option, title="Lane divider")
  assert lane_divider_option is not None, "Option 'Lane divider' not found under radio attribute 'Type?'"

  zebra_crossing_option = ooi_type_radio_attribute.get_child_by_title(type_=Option, title="Zebra crossing")
  assert zebra_crossing_option is not None, "Option 'Zebra crossing' not found under radio attribute 'Type?'"

  other_ooi_option = ooi_type_radio_attribute.get_child_by_title(type_=Option, title="Other")
  assert other_ooi_option is not None, "Option 'Other' not found under radio attribute 'Type?'"

  # Curb Qualities
  curb_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Qualities?")
  assert curb_checklist_attribute is not None, "Checklist attribute 'Qualities?' not found"

  curb_good_quality_option = curb_checklist_attribute.get_child_by_title(type_=Option, title="Good quality")
  assert curb_good_quality_option is not None, "Option 'Good quality' not found under 'Qualities?'"

  curb_well_lit_option = curb_checklist_attribute.get_child_by_title(type_=Option, title="Well lit")
  assert curb_well_lit_option is not None, "Option 'Well lit' not found under 'Qualities?'"

  curb_fully_visible_option = curb_checklist_attribute.get_child_by_title(type_=Option, title="Fully visible")
  assert curb_fully_visible_option is not None, "Option 'Fully visible' not found under 'Curb Qualities?'"

  # Lane divider Qualities
  lane_divider_checklist_attribute = ontology_structure.get_child_by_title(
      type_=ChecklistAttribute, title="Lane divider Qualities?"
  )
  assert lane_divider_checklist_attribute is not None, "Checklist attribute 'Lane divider Qualities?' not found"

  lane_divider_good_quality_option = lane_divider_checklist_attribute.get_child_by_title(
      type_=Option, title="Good quality"
  )
  assert lane_divider_good_quality_option is not None, "Option 'Good quality' not found under 'Lane divider Qualities?'"

  lane_divider_well_lit_option = lane_divider_checklist_attribute.get_child_by_title(type_=Option, title="Well lit")
  assert lane_divider_well_lit_option is not None, "Option 'Well lit' not found under 'Lane divider Qualities?'"

  lane_divider_fully_visible_option = lane_divider_checklist_attribute.get_child_by_title(
      type_=Option, title="Fully visible"
  )
  assert lane_divider_fully_visible_option is not None, "Option 'Fully visible' not found under 'Lane divider Qualities?'"

  # Zebra crossing Qualities
  zebra_crossing_checklist_attribute = ontology_structure.get_child_by_title(
      type_=ChecklistAttribute, title="Zebra crossing Qualities?"
  )
  assert zebra_crossing_checklist_attribute is not None, "Checklist attribute 'Zebra crossing Qualities?' not found"

  zebra_crossing_good_quality_option = zebra_crossing_checklist_attribute.get_child_by_title(
      type_=Option, title="Good quality"
  )
  assert zebra_crossing_good_quality_option is not None, (
      "Option 'Good quality' not found under 'Zebra crossing Qualities?'"
  )

  zebra_crossing_well_lit_option = zebra_crossing_checklist_attribute.get_child_by_title(type_=Option, title="Well lit")
  assert zebra_crossing_well_lit_option is not None, "Option 'Well lit' not found under 'Zebra crossing Qualities?'"

  zebra_crossing_fully_visible_option = zebra_crossing_checklist_attribute.get_child_by_title(
      type_=Option, title="Fully visible"
  )
  assert zebra_crossing_fully_visible_option is not None, (
      "Option 'Fully visible' not found under 'Zebra crossing Qualities?'"
  )

  # Other text attribute
  other_ooi_option_text_attribute = ontology_structure.get_child_by_title(type_=TextAttribute, title="Specify type")
  assert other_ooi_option_text_attribute is not None, "Text attribute 'Specify type' not found"

  # Dictionary of labels per data unit and per frame with type specified, including quality options
  pcd_labels = {
      "scene-1094": {
          0: {
              "label_ref": "ooi_001",
              "coordinates": PolylineCoordinates(
                  [
                      PointCoordinate3D(2.013, 2.02, 2.015),
                      PointCoordinate3D(3.033, 3.033, 3.033),
                      PointCoordinate3D(4.053, 4.023, 4.017),
                      PointCoordinate3D(5.043, 5.013, 5.043),
                  ]
              ),
              "ooi_type": "Curb",
              "curb_quality_options": "Good quality, Well lit",
          }
      },
      "scene-0916": {
          0: [
              {
                  "label_ref": "ooi_002",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(3.000, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 3.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Lane divider",
                  "lane_divider_quality_options": "Good quality, Well lit, Fully visible",
              },
              {
                  "label_ref": "ooi_003",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.300, 5.300, 0.000),
                          PointCoordinate3D(6.300, 6.300, 0.000),
                          PointCoordinate3D(8.300, 5.300, 0.000),
                          PointCoordinate3D(7.300, 4.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Zebra crossing",
                  "zebra_crossing_quality_options": "Good quality",
              },
              {
                  "label_ref": "ooi_004",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Other",
                  "Type": "Cane",
              },
          ],
      },
      "scene-0796": {
          0: {
              "label_ref": "ooi_005",
              "coordinates": PolylineCoordinates(
                  [
                      PointCoordinate3D(1.300, 2.300, 0.000),
                      PointCoordinate3D(3.300, 3.300, 0.000),
                      PointCoordinate3D(5.300, 2.300, 0.000),
                      PointCoordinate3D(4.300, 1.300, 0.000),
                  ]
              ),
              "ooi_type": "Curb",
              "curb_quality_options": "Good quality, Well lit",
          },
          2: [
              {
                  "label_ref": "ooi_006",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.300, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 2.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Lane divider",
                  "lane_divider_quality_options": "Fully visible",
              },
              {
                  "label_ref": "ooi_007",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.300, 5.300, 0.000),
                          PointCoordinate3D(6.300, 6.300, 0.000),
                          PointCoordinate3D(8.300, 5.300, 0.000),
                          PointCoordinate3D(7.300, 4.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Zebra crossing",
                  "zebra_crossing_quality_options": "Good quality",
              },
              {
                  "label_ref": "ooi_008",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Other",
                  "Type": "Cane",
              },
          ],
      },
      "scene-1100": {
          0: {
              "label_ref": "ooi_009",
              "coordinates": PolylineCoordinates(
                  [
                      PointCoordinate3D(1.300, 2.300, 0.000),
                      PointCoordinate3D(3.300, 3.300, 0.000),
                      PointCoordinate3D(5.300, 2.300, 0.000),
                      PointCoordinate3D(4.300, 1.300, 0.000),
                  ]
              ),
              "ooi_type": "Curb",
              "curb_quality_options": "Good quality",
          },
          3: [
              {
                  "label_ref": "ooi_010",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.300, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 2.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Lane divider",
                  "lane_divider_quality_options": "Good quality, Well lit, Fully visible",
              },
              {
                  "label_ref": "ooi_011",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.300, 5.300, 0.000),
                          PointCoordinate3D(6.300, 6.300, 0.000),
                          PointCoordinate3D(8.300, 5.300, 0.000),
                          PointCoordinate3D(7.300, 4.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Zebra crossing",
                  "zebra_crossing_quality_options": "Good quality",
              },
              {
                  "label_ref": "ooi_012",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Other",
                  "Type": "Cane",
              },
          ],
      },
      "scene-0655": {
          13: [
              {
                  "label_ref": "ooi_013",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.300, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 2.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Zebra crossing",
                  "zebra_crossing_quality_options": "Good quality",
              },
              {
                  "label_ref": "ooi_014",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.300, 5.300, 0.000),
                          PointCoordinate3D(6.300, 6.300, 0.000),
                          PointCoordinate3D(8.300, 5.300, 0.000),
                          PointCoordinate3D(7.300, 4.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Curb",
                  "curb_quality_options": "Good quality, Well lit, Fully visible",
              },
              {
                  "label_ref": "ooi_015",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Other",
                  "Type": "Cane",
              },
          ],
          14: [
              {
                  "label_ref": "ooi_016",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.300, 2.300, 0.000),
                          PointCoordinate3D(3.300, 3.300, 0.000),
                          PointCoordinate3D(5.300, 2.300, 0.000),
                          PointCoordinate3D(4.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Zebra crossing",
                  "zebra_crossing_quality_options": "Good quality",
              },
              {
                  "label_ref": "ooi_014",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.130, 5.230, 0.000),
                          PointCoordinate3D(6.130, 6.230, 0.000),
                          PointCoordinate3D(8.130, 5.230, 0.000),
                          PointCoordinate3D(7.130, 4.230, 0.000),
                      ]
                  ),
                  "ooi_type": "Curb",
                  "curb_quality_options": "Good quality, Well lit, Fully visible",
              },
              {
                  "label_ref": "ooi_017",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.300, 2.300, 0.000),
                          PointCoordinate3D(9.300, 3.300, 0.000),
                          PointCoordinate3D(11.300, 2.300, 0.000),
                          PointCoordinate3D(10.300, 1.300, 0.000),
                      ]
                  ),
                  "ooi_type": "Other",
                  "Type": "Cane",
              },
          ],
          15: [
              {
                  "label_ref": "ooi_016",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(1.130, 2.230, 0.000),
                          PointCoordinate3D(3.130, 3.230, 0.000),
                          PointCoordinate3D(5.130, 2.230, 0.000),
                          PointCoordinate3D(4.130, 1.230, 0.000),
                      ]
                  ),
                  "ooi_type": "Zebra crossing",
                  "zebra_crossing_quality_options": "Good quality",
              },
              {
                  "label_ref": "ooi_014",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(4.330, 5.530, 0.000),
                          PointCoordinate3D(6.330, 6.530, 0.000),
                          PointCoordinate3D(8.330, 5.530, 0.000),
                          PointCoordinate3D(7.330, 4.530, 0.000),
                      ]
                  ),
                  "ooi_type": "Curb",
                  "curb_quality_options": "Good quality, Well lit, Fully visible",
              },
              {
                  "label_ref": "ooi_017",
                  "coordinates": PolylineCoordinates(
                      [
                          PointCoordinate3D(7.130, 2.230, 0.000),
                          PointCoordinate3D(9.130, 3.230, 0.000),
                          PointCoordinate3D(11.130, 2.230, 0.000),
                          PointCoordinate3D(10.130, 1.230, 0.000),
                      ]
                  ),
                  "ooi_type": "Other",
                  "Type": "Cane",
              },
          ],
      },
  }

  # Cache label rows after initialization
  label_row_map = {}

  # Step 1: Initialize all label rows using a bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_unit in pcd_labels.keys():
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"

          if not label_rows:
              print(f"Skipping: No label row found for {data_unit}")
              continue

          label_row = label_rows[0]
          label_row.initialise_labels(bundle=bundle)
          assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

          label_row_map[data_unit] = label_row  # Cache the initialized label row

  # Step 2: Process all frame coordinates and prepare label rows for saving
  label_rows_to_save = []

  for data_unit, frame_coordinates in pcd_labels.items():
      label_row = label_row_map.get(data_unit)
      assert label_row is not None, f"Label row not initialized for {data_unit}"

      object_instances_by_label_ref = {}

      for frame_number, items in frame_coordinates.items():
          assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"
          if not isinstance(items, list):
              items = [items]

          for item in items:
              label_ref = item["label_ref"]
              coord = item["coordinates"]
              ooi_type = item["ooi_type"]

              assert ooi_type in {
                  "Curb",
                  "Lane divider",
                  "Zebra crossing",
                  "Other",
              }, f"Unexpected type '{ooi_type}' in {data_unit}"

              if label_ref not in object_instances_by_label_ref:
                  polyline_object_instance: ObjectInstance = polyline_ontology_object.create_instance()
                  assert polyline_object_instance is not None, "Failed to create ObjectInstance"
                  checklist_attribute = None
                  quality_options = []

                  # Assign radio and checklist attributes based on the type
                  if ooi_type == "Curb":
                      assert curb_option is not None, "Missing 'curb_option'"
                      polyline_object_instance.set_answer(attribute=ooi_type_radio_attribute, answer=curb_option)
                      checklist_attribute = curb_checklist_attribute
                      quality_options = [q.strip() for q in item.get("curb_quality_options", "").split(",") if q.strip()]
                  elif ooi_type == "Lane divider":
                      assert lane_divider_option is not None, "Missing 'lane_divider_option'"
                      polyline_object_instance.set_answer(attribute=ooi_type_radio_attribute, answer=lane_divider_option)
                      checklist_attribute = lane_divider_checklist_attribute
                      quality_options = [
                          q.strip() for q in item.get("lane_divider_quality_options", "").split(",") if q.strip()
                      ]
                  elif ooi_type == "Zebra crossing":
                      assert zebra_crossing_option is not None, "Missing 'zebra_crossing_option'"
                      polyline_object_instance.set_answer(
                          attribute=ooi_type_radio_attribute, answer=zebra_crossing_option
                      )
                      checklist_attribute = zebra_crossing_checklist_attribute
                      quality_options = [
                          q.strip() for q in item.get("zebra_crossing_quality_options", "").split(",") if q.strip()
                      ]
                  elif ooi_type == "Other":
                      assert other_ooi_option is not None, "Missing 'other_ooi_option'"
                      polyline_object_instance.set_answer(attribute=ooi_type_radio_attribute, answer=other_ooi_option)
                      text_answer = item.get("Type", "")
                      assert isinstance(text_answer, str), "'Type' must be a string"
                      polyline_object_instance.set_answer(attribute=other_ooi_option_text_attribute, answer=text_answer)
                      quality_options = []

                  # Process checklist options
                  checklist_answers = []
                  for quality in quality_options:
                      option = None
                      if quality == "Good quality":
                          option = (
                              curb_good_quality_option
                              if ooi_type == "Curb"
                              else lane_divider_good_quality_option
                              if ooi_type == "Lane divider"
                              else zebra_crossing_good_quality_option
                              if ooi_type == "Zebra crossing"
                              else None
                          )
                      elif quality == "Well lit":
                          option = (
                              curb_well_lit_option
                              if ooi_type == "Curb"
                              else lane_divider_well_lit_option
                              if ooi_type == "Lane divider"
                              else zebra_crossing_well_lit_option
                              if ooi_type == "Zebra crossing"
                              else None
                          )
                      elif quality == "Fully visible":
                          option = (
                              curb_fully_visible_option
                              if ooi_type == "Curb"
                              else lane_divider_fully_visible_option
                              if ooi_type == "Lane divider"
                              else zebra_crossing_fully_visible_option
                              if ooi_type == "Zebra crossing"
                              else None
                          )

                      if option:
                          checklist_answers.append(option)
                      else:
                          assert ooi_type == "Other", f"Invalid quality '{quality}' for type '{ooi_type}'"

                  if checklist_attribute and checklist_answers:
                      polyline_object_instance.set_answer(
                          attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                      )

                  object_instances_by_label_ref[label_ref] = polyline_object_instance

              else:
                  polyline_object_instance = object_instances_by_label_ref[label_ref]

              # Assign coordinates for this frame
              polyline_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

      # Add object instances to the label row if they have frames assigned
      for polyline_object_instance in object_instances_by_label_ref.values():
          assert isinstance(polyline_object_instance, ObjectInstance), "Expected ObjectInstance type"
          if polyline_object_instance.get_annotation_frames():
              label_row.add_object_instance(polyline_object_instance)

      label_rows_to_save.append(label_row)

  # Step 3: Save all label rows using a bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows_to_save:
          assert label_row is not None, "Trying to save a None label row"
          label_row.save(bundle=bundle)
          print(f"Saved label row for {label_row.data_title}")

  print("Labels with radio buttons, checklist attributes, and text labels added for all data units.")
  ```
</CodeGroup>

## Keypoints 3D

**Basic**

This example includes the following:

* Keypoints 3D labeling

**Advanced**

This example includes the following:

* Keypoint 3D labeling
* Radio button options
* Checklist options
* Text input

**Keypoint Ontology**

![Keypoint 3D Ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/ontologies/ontology-pcd-keypoints.png)

<CodeGroup>
  ```python 3D Keypoints - Basic expandable theme={"dark"}

  # 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."

  # Dictionary of labels per data unit and per frame with Point of Interest
  pcd_labels = {
      "scene-1094": {
          1: {
              "label_ref": "poi_001",
              "coordinates": PointCoordinate3D(x=0.01, y=0.02, z=0.03)
          }
      },
      "scene-0916": {
          1: [
              {
                  "label_ref": "poi_002",
                  "coordinates": PointCoordinate3D(x=0.03, y=0.03, z=0.03)
              },
              {
                  "label_ref": "poi_003",
                  "coordinates": PointCoordinate3D(x=0.5, y=0.4, z=0.3)
              },
              {
                  "label_ref": "poi_004",
                  "coordinates": PointCoordinate3D(x=0.9, y=0.3, z=0.3)
              },
          ],
      },
      "scene-0796": {
          0: {
              "label_ref": "poi_005",
              "coordinates": PointCoordinate3D(x=0.05, y=0.02, z=0.03)
          },
          2: [
              {
                  "label_ref": "poi_006",
                  "coordinates": PointCoordinate3D(x=0.3, y=0.3, z=0.3)
              },
              {
                  "label_ref": "poi_007",
                  "coordinates": PointCoordinate3D(x=0.4, y=0.5, z=0.3)
              },
              {
                  "label_ref": "poi_008",
                  "coordinates": PointCoordinate3D(x=0.11, y=0.2, z=0.3)
              },
          ],
      },
      "scene-1100": {
          0: {
              "label_ref": "poi_009",
              "coordinates": PointCoordinate3D(x=0.1, y=0.2, z=0.3)
          },
          3: [
              {
                  "label_ref": "poi_010",
                  "coordinates": PointCoordinate3D(x=0.3, y=0.3, z=0.3)
              },
              {
                  "label_ref": "poi_011",
                  "coordinates": PointCoordinate3D(x=0.8, y=0.5, z=0.3)
              },
              {
                  "label_ref": "poi_012",
                  "coordinates": PointCoordinate3D(x=0.11, y=0.2, z=0.3)
              },
          ],
      },
      "scene-0655": {
          1: [
              {
                  "label_ref": "poi_013",
                  "coordinates": PointCoordinate3D(x=0.2, y=0.1, z=0.3)
              },
              {
                  "label_ref": "poi_014",
                  "coordinates": PointCoordinate3D(x=0.6, y=0.6, z=0.3)
              },
              {
                  "label_ref": "poi_015",
                  "coordinates": PointCoordinate3D(x=0.10, y=0.1, z=0.3)
              },
          ],
          2: [
              {
                  "label_ref": "poi_016",
                  "coordinates": PointCoordinate3D(x=0.4, y=0.1, z=0.3)
              },
              {
                  "label_ref": "poi_014",
                  "coordinates": PointCoordinate3D(x=0.8, y=0.5, z=0.3)
              },
              {
                  "label_ref": "poi_017",
                  "coordinates": PointCoordinate3D(x=0.11, y=0.2, z=0.3)
              },
          ],
          3: [
              {
                  "label_ref": "poi_016",
                  "coordinates": PointCoordinate3D(x=0.5, y=0.2, z=0.3)
              },
              {
                  "label_ref": "poi_014",
                  "coordinates": PointCoordinate3D(x=0.7, y=0.4, z=0.3)
              },
              {
                  "label_ref": "poi_017",
                  "coordinates": PointCoordinate3D(x=0.9, y=0.3, z=0.3)
              },
          ],
      },
  }


  # Initialize label rows
  label_row_map = {}
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_title in pcd_labels.keys():
          rows = project.list_label_rows_v2(data_title_eq=data_title)
          if not rows:
              print(f"Skipping: No label row found for {data_title}")
              continue
          lr = rows[0]
          lr.initialise_labels(bundle=bundle)
          label_row_map[data_title] = lr

  # Create instances
  label_rows_to_save = []
  for data_title, frames in pcd_labels.items():
      lr = label_row_map.get(data_title)
      if not lr:
          continue

      instances_by_ref = {}

      for frame_no, items in frames.items():
          # normalize to list
          items = items if isinstance(items, list) else [items]

          for item in items:
              ref = item["label_ref"]
              coords = item["coordinates"]

              if ref not in instances_by_ref:
                  instances_by_ref[ref] = keypoint_ontology_object.create_instance()

              instances_by_ref[ref].set_for_frames(coordinates=coords, frames=frame_no)

      # Add only instances that have at least one frame
      for inst in instances_by_ref.values():
          if inst.get_annotation_frames():
              lr.add_object_instance(inst)

      label_rows_to_save.append(lr)

  # Save all label rows
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for lr in label_rows_to_save:
          lr.save(bundle=bundle)
          print(f"Saved label row for {lr.data_title}")
  ```

  ```python 3D Keypoints - Advanced expandable theme={"dark"}

  # 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 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)
  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 keypoint object for Point of Interest
  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"

  # Get radio attribute for Point of Interest type
  poi_type_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Type?")
  assert poi_type_radio_attribute is not None, "Radio attribute 'Type?' not found"

  # Get radio options
  sign_option = poi_type_radio_attribute.get_child_by_title(type_=Option, title="Sign")
  assert sign_option is not None, "Option 'Sign' not found under radio attribute 'Type?'"

  traffic_light_option = poi_type_radio_attribute.get_child_by_title(type_=Option, title="Traffic light")
  assert traffic_light_option is not None, "Option 'Traffic light' not found under radio attribute 'Type?'"

  other_poi_option = poi_type_radio_attribute.get_child_by_title(type_=Option, title="Other Point of Interest type")
  assert other_poi_option is not None, "Option 'Other Point of Interest type' not found under radio attribute 'Type?'"

  # Get checklist attributes and options for Sign
  sign_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="Sign Qualities?")
  assert sign_checklist_attribute is not None, "Checklist attribute 'Sign Qualities?' not found"

  sign_well_positioned_option = sign_checklist_attribute.get_child_by_title(type_=Option, title="Well positioned")
  assert sign_well_positioned_option is not None, "Option 'Well positioned' not found under 'Sign Qualities?'"

  sign_good_visibility_option = sign_checklist_attribute.get_child_by_title(type_=Option, title="Good visibility")
  assert sign_good_visibility_option is not None, "Option 'Good visibility' not found under 'Sign Qualities?'"

  sign_good_condition_option = sign_checklist_attribute.get_child_by_title(
      type_=Option, title="Good condition")
  assert sign_good_condition_option is not None, "Option 'Good condition' not found under 'Sign Qualities?'"

  # Get checklist attributes and options for Traffic light
  traffic_light_checklist_attribute = ontology_structure.get_child_by_title(
      type_=ChecklistAttribute, title="Traffic light Qualities?"
  )
  assert traffic_light_checklist_attribute is not None, "Checklist attribute 'Traffic light Qualities?' not found"

  traffic_light_well_positioned_option = traffic_light_checklist_attribute.get_child_by_title(
      type_=Option, title="Well positioned"
  )
  assert traffic_light_well_positioned_option is not None, "Option 'Well positioned' not found under 'Traffic light Qualities?'"

  traffic_light_good_visibility_option = traffic_light_checklist_attribute.get_child_by_title(
      type_=Option, title="Good visibility"
  )
  assert traffic_light_good_visibility_option is not None, "Option 'Good visibility' not found under 'Traffic light Qualities?'"

  traffic_light_good_condition_option = traffic_light_checklist_attribute.get_child_by_title(type_=Option, title="Good condition")
  assert traffic_light_good_condition_option is not None, "Option 'Good condition' not found under 'Traffic light Qualities?'"

  # Get text attribute for specifying other Point of Interest types
  other_poi_option_text_attribute = ontology_structure.get_child_by_title(
      type_=TextAttribute, title="Specify Point of Interest type"
  )
  assert other_poi_option_text_attribute is not None, "Text attribute 'Specify Point of Interest type' not found"

  # Dictionary of labels per data unit and per frame with Point of Interest type specified, including quality options
  pcd_labels = {
      "scene-1094": {
          1: {
              "label_ref": "poi_001",
              "coordinates": PointCoordinate3D(x=0.01, y=0.02, z=0.03),
              "poi_type": "Sign",
              "sign_quality_options": "Well positioned, Good visibility, Good condition",
          }
      },
      "scene-0916": {
          1: [
              {
                  "label_ref": "poi_002",
                  "coordinates": PointCoordinate3D(x=0.03, y=0.03, z=0.03),
                  "poi_type": "Traffic light",
                  "traffic_light_quality_options": "Well positioned, Good visibility, Good condition",
              },
              {
                  "label_ref": "poi_003",
                  "coordinates": PointCoordinate3D(x=0.5, y=0.4, z=0.3),
                  "poi_type": "Traffic light",
                  "traffic_light_quality_options": "Good visibility",
              },
              {
                  "label_ref": "poi_004",
                  "coordinates": PointCoordinate3D(x=0.9, y=0.3, z=0.3),
                  "poi_type": "Other Point of Interest type",
                  "Specify Point of Interest type": "Curb",
              },
          ],
      },
      "scene-0796": {
          0: {
              "label_ref": "poi_005",
              "coordinates": PointCoordinate3D(x=0.05, y=0.02, z=0.03),
              "poi_type": "Sign",
              "sign_quality_options": "Well positioned, Good visibility, Good condition",
          },
          2: [
              {
                  "label_ref": "poi_006",
                  "coordinates": PointCoordinate3D(x=0.3, y=0.3, z=0.3),
                  "poi_type": "Sign",
                  "sign_quality_options": "Good condition",
              },
              {
                  "label_ref": "poi_007",
                  "coordinates": PointCoordinate3D(x=0.4, y=0.5, z=0.3),
                  "poi_type": "Sign",
                  "sign_quality_options": "Good visibility",
              },
              {
                  "label_ref": "poi_008",
                  "coordinates": PointCoordinate3D(x=0.11, y=0.2, z=0.3),
                  "poi_type": "Other Point of Interest type",
                  "Specify Point of Interest type": "Post box",
              },
          ],
      },
      "scene-1100": {
          0: {
              "label_ref": "poi_009",
              "coordinates": PointCoordinate3D(x=0.1, y=0.2, z=0.3),
              "poi_type": "Traffic light",
              "traffic_light_quality_options": "Well positioned, Good visibility, Good condition",
          },
          3: [
              {
                  "label_ref": "poi_010",
                  "coordinates": PointCoordinate3D(x=0.3, y=0.3, z=0.3),
                  "poi_type": "Traffic light",
                  "traffic_light_quality_options": "Well positioned, Good visibility, Good condition",
              },
              {
                  "label_ref": "poi_011",
                  "coordinates": PointCoordinate3D(x=0.8, y=0.5, z=0.3),
                  "poi_type": "Traffic light",
                  "traffic_light_quality_options": "Good condition",
              },
              {
                  "label_ref": "poi_012",
                  "coordinates": PointCoordinate3D(x=0.11, y=0.2, z=0.3),
                  "poi_type": "Other Point of Interest type",
                  "Specify Point of Interest type": "Post box",
              },
          ],
      },
      "scene-0655": {
          1: [
              {
                  "label_ref": "poi_013",
                  "coordinates": PointCoordinate3D(x=0.2, y=0.1, z=0.3),
                  "poi_type": "Sign",
                  "sign_quality_options": "Good condition",
              },
              {
                  "label_ref": "poi_014",
                  "coordinates": PointCoordinate3D(x=0.6, y=0.6, z=0.3),
                  "poi_type": "Sign",
                  "sign_quality_options": "Well positioned, Good visibility, Good condition",
              },
              {
                  "label_ref": "poi_015",
                  "coordinates": PointCoordinate3D(x=0.10, y=0.1, z=0.3),
                  "poi_type": "Other Point of Interest type",
                  "Specify Point of Interest type": "Curb",
              },
          ],
          2: [
              {
                  "label_ref": "poi_016",
                  "coordinates": PointCoordinate3D(x=0.4, y=0.1, z=0.3),
                  "poi_type": "Sign",
                  "sign_quality_options": "Good condition",
              },
              {
                  "label_ref": "poi_014",
                  "coordinates": PointCoordinate3D(x=0.8, y=0.5, z=0.3),
                  "poi_type": "Sign",
                  "sign_quality_options": "Well positioned, Good visibility, Good condition",
              },
              {
                  "label_ref": "poi_017",
                  "coordinates": PointCoordinate3D(x=0.11, y=0.2, z=0.3),
                  "poi_type": "Other Point of Interest type",
                  "Specify Point of Interest type": "Post box",
              },
          ],
          3: [
              {
                  "label_ref": "poi_016",
                  "coordinates": PointCoordinate3D(x=0.5, y=0.2, z=0.3),
                  "poi_type": "Sign",
                  "sign_quality_options": "Good condition",
              },
              {
                  "label_ref": "poi_014",
                  "coordinates": PointCoordinate3D(x=0.7, y=0.4, z=0.3),
                  "poi_type": "Sign",
                  "sign_quality_options": "Well positioned, Good visibility, Good condition",
              },
              {
                  "label_ref": "poi_017",
                  "coordinates": PointCoordinate3D(x=0.9, y=0.3, z=0.3),
                  "poi_type": "Other Point of Interest type",
                  "Specify Point of Interest type": "Post box",
              },
          ],
      },
  }


  # Cache label rows after initialization
  label_row_map = {}

  # Step 1: Initialize all label rows using a bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_unit in pcd_labels.keys():
          label_rows = project.list_label_rows_v2(data_title_eq=data_unit)
          assert isinstance(label_rows, list), f"Expected list of label rows for '{data_unit}', got {type(label_rows)}"

          if not label_rows:
              print(f"Skipping: No label row found for {data_unit}")
              continue

          label_row = label_rows[0]
          label_row.initialise_labels(bundle=bundle)
          assert label_row.ontology_structure is not None, f"Ontology not initialized for label row: {data_unit}"

          label_row_map[data_unit] = label_row  # Cache the initialized label row

  # Step 2: Process all frame coordinates and prepare label rows for saving
  label_rows_to_save = []

  for data_unit, frame_coordinates in pcd_labels.items():
      label_row = label_row_map.get(data_unit)
      assert label_row is not None, f"Label row not initialized for {data_unit}"

      object_instances_by_label_ref = {}

      for frame_number, items in frame_coordinates.items():
          assert isinstance(frame_number, int), f"Frame number must be int, got {type(frame_number)}"
          if not isinstance(items, list):
              items = [items]

          for item in items:
              label_ref = item["label_ref"]
              coord = item["coordinates"]
              poi_type = item["poi_type"]

              assert poi_type in {
                  "Sign",
                  "Traffic light",
                  "Other Point of Interest type",
              }, f"Unexpected type '{poi_type}' in {data_unit}"

              if label_ref not in object_instances_by_label_ref:
                  keypoint_object_instance: ObjectInstance = keypoint_ontology_object.create_instance()
                  assert keypoint_object_instance is not None, "Failed to create ObjectInstance"
                  checklist_attribute = None
                  quality_options = []

                  # Assign radio and checklist attributes based on the type
                  if poi_type == "Sign":
                      assert sign_option is not None, "Missing 'sign_type'"
                      keypoint_object_instance.set_answer(attribute=poi_type_radio_attribute, answer=sign_option)
                      checklist_attribute = sign_checklist_attribute
                      quality_options = [q.strip() for q in item.get("sign_quality_options", "").split(",") if q.strip()]
                  elif poi_type == "Traffic light":
                      assert traffic_light_option is not None, "Missing 'lane_divider_option'"
                      keypoint_object_instance.set_answer(attribute=poi_type_radio_attribute, answer=traffic_light_option)
                      checklist_attribute = traffic_light_checklist_attribute
                      quality_options = [
                          q.strip() for q in item.get("traffic_light_quality_options", "").split(",") if q.strip()
                      ]
                  elif poi_type == "Other Point of Interest type":
                      assert other_poi_option is not None, "Missing 'other_ooi_option'"
                      keypoint_object_instance.set_answer(attribute=poi_type_radio_attribute, answer=other_poi_option)
                      text_answer = item.get("Type", "")
                      assert isinstance(text_answer, str), "'Type' must be a string"
                      keypoint_object_instance.set_answer(attribute=other_poi_option_text_attribute, answer=text_answer)
                      quality_options = []

                  # Process checklist options
                  checklist_answers = []
                  for quality in quality_options:
                      option = None
                      if quality == "Well positioned":
                          option = (
                              sign_well_positioned_option
                              if poi_type == "Sign"
                              else traffic_light_well_positioned_option
                              if poi_type == "Traffic light"
                              else None
                          )
                      elif quality == "Good visibility":
                          option = (
                              sign_good_visibility_option
                              if poi_type == "Sign"
                              else traffic_light_good_visibility_option
                              if poi_type == "Traffic light"
                              else None
                          )
                      elif quality == "Good condition":
                          option = (
                              sign_good_condition_option
                              if poi_type == "Sign"
                              else traffic_light_good_condition_option
                              if poi_type == "Traffic light"
                              else None
                          )

                      if option:
                          checklist_answers.append(option)
                      else:
                          assert poi_type == "Other Point of Interest type", f"Invalid quality '{quality}' for type '{poi_type}'"

                  if checklist_attribute and checklist_answers:
                      keypoint_object_instance.set_answer(
                          attribute=checklist_attribute, answer=checklist_answers, overwrite=True
                      )

                  object_instances_by_label_ref[label_ref] = keypoint_object_instance

              else:
                  keypoint_object_instance = object_instances_by_label_ref[label_ref]

              # Assign coordinates for this frame
              keypoint_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

      # Add object instances to the label row if they have frames assigned
      for keypoint_object_instance in object_instances_by_label_ref.values():
          assert isinstance(keypoint_object_instance, ObjectInstance), "Expected ObjectInstance type"
          if keypoint_object_instance.get_annotation_frames():
              label_row.add_object_instance(keypoint_object_instance)

      label_rows_to_save.append(label_row)

  # Step 3: Save all label rows using a bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows_to_save:
          assert label_row is not None, "Trying to save a None label row"
          label_row.save(bundle=bundle)
          print(f"Saved label row for {label_row.data_title}")

  print("Labels with radio buttons, checklist attributes, and text labels added for all data units.")
  ```
</CodeGroup>

## Segmentations

The following script demonstrates how to add segmentation labels to point cloud data using the Encord Python SDK. It assumes that you have a project with a point cloud dataset and an ontology that includes a segmentation object titled "Sidewalk". The script creates segmentation instances for specified ranges of point indices in the point cloud files. If the scene was uploaded as [shown in the example here](/sdk-documentation/index-sdk/sdk-scenes#add-multi-frame-sensor-streams), with one label space per frame, a space's index in this list corresponds to its frame number.

<CodeGroup>
  ```python theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient, Project
  from encord.objects import Object
  from encord.objects.frames import Range
  from encord.objects.spaces.range_space.point_cloud_space import PointCloudFileSpace


  # 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)

  # Find a point-cloud segmentation object in the project ontology
  ontology_structure = project.ontology_structure
  segmentation_ontology_object: Object = ontology_structure.get_child_by_title(title="Sidewalk", type_=Object)
  assert segmentation_ontology_object is not None, "Segmentation object 'Sidewalk' not found in ontology."

  # Point-index ranges per data unit. Each entry becomes one segmentation instance owning
  # the listed (start, end) inclusive point-index ranges in the uploaded point cloud.
  # Ranges must be computed against the exact file registered on the platform - re-uploading,
  # reordering, or decimating the cloud afterwards shifts every index.
  pcd_segmentation_labels = {
      "scene-1094": [
          {
              "label_ref": "sidewalk_001",
              "ranges": [(0, 15234), (52000, 52980)],
          },
          {
              "label_ref": "sidewalk_002",
              "ranges": [(15235, 28110)],
          },
      ],
      "scene-0916": [
          {
              "label_ref": "sidewalk_003",
              "ranges": [(0, 40233), (40500, 61022), (70000, 70999)],
          },
      ],
  }

  # Initialize label rows
  label_row_map = {}
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_title in pcd_segmentation_labels.keys():
          rows = project.list_label_rows_v2(data_title_eq=data_title)
          if not rows:
              print(f"Skipping: No label row found for {data_title}")
              continue
          lr = rows[0]
          lr.initialise_labels(bundle=bundle)
          label_row_map[data_title] = lr

  # Create instances
  label_rows_to_save = []
  for data_title, crowns in pcd_segmentation_labels.items():
      lr = label_row_map.get(data_title)
      if not lr:
          continue

      # Point-cloud segmentation instances live on the data unit's point-cloud space, not
      # directly on the label row. Rather than constructing a space identifier, list every
      # space on the row and pick out the point-cloud one, taking the first match.
      # If the scene was uploaded as advised, with one label space per frame, a space's
      # index in this list corresponds to its frame number - so index 0 is frame 0, which is what this example labels.
      spaces = lr.get_spaces()
      point_cloud_spaces = [s for s in spaces if isinstance(s, PointCloudFileSpace)]
      assert len(point_cloud_spaces) > 0, f"No point cloud spaces found for {data_title}"
      space = point_cloud_spaces[68]

      for crown in crowns:
          instance = segmentation_ontology_object.create_instance()
          ranges = [Range(start=s, end=e) for s, e in crown["ranges"]]
          space.put_object_instance(
              object_instance=instance,
              ranges=ranges,
              confidence=1.0,
          )

      label_rows_to_save.append(lr)

  # Save all label rows
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for lr in label_rows_to_save:
          lr.save(bundle=bundle)
          print(f"Saved label row for {lr.data_title}")

  ```
</CodeGroup>


# Text Files
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-labels-text-files



## Import Text Regions to Text Files

A single `text region` object label can be added at a character range between `start` and `end` using `range`.

**Text Region Ontology**

![Text region ontology](https://storage.googleapis.com/docs-media.encord.com/static/img/sdk/labels-text-region.png)

<CodeGroup>
  ```python Text Regions - Text Files - Basic expandable theme={"dark"}

  from encord import EncordUserClient, Project
  from encord.objects import Object, ObjectInstance
  from encord.objects.coordinates import TextCoordinates
  from encord.objects.frames import Range
  from encord.objects.attributes import RadioAttribute, TextAttribute, Option

  # 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 Project ID
  BUNDLE_SIZE = 100

  # Authorize connection to Encord
  user_client: EncordUserClient = 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",
  )

  # Get project
  project: Project = user_client.get_project(PROJECT_ID)
  assert project is not None, f"Project with ID {PROJECT_ID} not found."

  # Ontology verification
  ontology_structure = project.ontology_structure
  assert ontology_structure is not None, "Ontology structure not found in the project."

  text_object: Object = ontology_structure.get_child_by_title(title="Edit", type_=Object)
  assert text_object is not None, "Ontology object for 'Edit' not found."

  correction_radio_attribute = ontology_structure.get_child_by_title(
      type_=RadioAttribute, title="Corrections"
  )
  assert correction_radio_attribute is not None, "Radio attribute 'Corrections' not found."

  english_correction_option = correction_radio_attribute.get_child_by_title(
      type_=Option, title="English corrections"
  )
  assert english_correction_option is not None, "Option 'English corrections' not found under 'Corrections'."

  english_correction_text_attribute = english_correction_option.get_child_by_title(
      type_=TextAttribute, title="Correction text"
  )
  assert english_correction_text_attribute is not None, (
      "Text attribute 'Correction text' not found under 'English corrections'."
  )

  # Labels
  text_annotations = {
      "paradise-lost.txt": [
          {
              "label_ref": "text_region_001",
              "coordinates": Range(start=5000, end=5050),
              "correction_text": "This needs to be updated for clarity.",
          },
          {
              "label_ref": "text_region_002",
              "coordinates": Range(start=6000, end=6050),
              "correction_text": "Rephrase for better readability.",
          },
      ],
      "War and Peace.txt": [
          {
              "label_ref": "text_region_003",
              "coordinates": Range(start=3000, end=3050),
              "correction_text": "Grammar correction required.",
          },
          {
              "label_ref": "text_region_004",
              "coordinates": Range(start=4000, end=4050),
              "correction_text": "Check for historical accuracy.",
          },
      ],
  }

  # Initialize label rows
  label_row_map = {}

  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_title in text_annotations.keys():
          label_rows = project.list_label_rows_v2(data_title_eq=data_title)
          if not label_rows:
              print(f"Skipping: No label row found for {data_title}")
              continue
          lr = label_rows[0]
          lr.initialise_labels(bundle=bundle)
          label_row_map[data_title] = lr

  # Apply labels
  label_rows_to_save = []

  for data_title, annotations in text_annotations.items():
      lr = label_row_map.get(data_title)
      if lr is None:
          print(f"Skipping: No initialized label row found for {data_title}")
          continue

      for ann in annotations:
          coord = TextCoordinates(range=[ann["coordinates"]])

          inst: ObjectInstance = text_object.create_instance()
          inst.set_for_frames(frames=0, coordinates=coord)
          inst.set_answer(attribute=correction_radio_attribute, answer=english_correction_option)
          inst.set_answer(attribute=english_correction_text_attribute, answer=ann["correction_text"])
          lr.add_object_instance(inst)

          print(f"Added [English correction] text region {ann['label_ref']} to {data_title}")

      label_rows_to_save.append(lr)

  # Save label rows
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for lr in label_rows_to_save:
          lr.save(bundle=bundle)
          print(f"Saved label row for {lr.data_title}")

  print("English correction labels applied.")
  ```

  ```python Text Regions - Text Files - Advanced expandable theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient, Project
  from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
  from encord.objects.coordinates import TextCoordinates
  from encord.objects.frames import Range

  # 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 Project ID
  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
  project: Project = user_client.get_project(PROJECT_ID)
  assert project is not None, f"Project with ID {PROJECT_ID} not found."

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

  # Find ontology object for Text Region
  text_object: Object = ontology_structure.get_child_by_title(title="Edit", type_=Object)
  assert text_object is not None, "Ontology object for 'Edit' not found."

  # Define radio attributes for corrections
  correction_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Corrections")
  assert correction_radio_attribute is not None, "Radio attribute 'Corrections' not found."

  english_correction_option = correction_radio_attribute.get_child_by_title(type_=Option, title="English corrections")
  assert english_correction_option is not None, (
      "Option 'English corrections' not found under 'Corrections' radio attribute."
  )

  chinese_correction_option = correction_radio_attribute.get_child_by_title(type_=Option, title="繁體中文修正")
  assert chinese_correction_option is not None, "Option '繁體中文修正' not found under 'Corrections' radio attribute."

  # Define checklist attributes for each correction type
  english_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="English")
  assert english_checklist_attribute is not None, "Checklist attribute 'English' not found."

  en_ca_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-ca")
  assert en_ca_option is not None, "Option 'en-ca' not found under 'English' checklist attribute."

  en_gb_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-gb")
  assert en_gb_option is not None, "Option 'en-gb' not found under 'English' checklist attribute."

  en_us_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-us")
  assert en_us_option is not None, "Option 'en-us' not found under 'English' checklist attribute."

  chinese_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="繁體中文")
  assert chinese_checklist_attribute is not None, "Checklist attribute '繁體中文' not found."

  zh_tw_option = chinese_checklist_attribute.get_child_by_title(type_=Option, title="zh-tw")
  assert zh_tw_option is not None, "Option 'zh-tw' not found under '繁體中文' checklist attribute."

  zh_hk_option = chinese_checklist_attribute.get_child_by_title(type_=Option, title="zh-hk")
  assert zh_hk_option is not None, "Option 'zh-hk' not found under '繁體中文' checklist attribute."

  # Define text attributes for user-provided corrections
  english_correction_text_attribute = english_correction_option.get_child_by_title(
      type_=TextAttribute, title="Correction text"
  )
  assert english_correction_text_attribute is not None, (
      "Text attribute 'Correction text' not found under 'English corrections' option."
  )

  chinese_correction_text_attribute = ontology_structure.get_child_by_title(type_=TextAttribute, title="更正")
  assert chinese_correction_text_attribute is not None, "Text attribute '更正' not found."

  # Mapping of text files to multiple text regions with manual corrections
  text_annotations = {
      "Paradise Lost.txt": [
          {
              "label_ref": "text_region_001",
              "coordinates": Range(start=5000, end=5050),
              "languages": "en-ca, en-us",
              "correction_text": "This needs to be updated for clarity.",
          },
          {
              "label_ref": "text_region_002",
              "coordinates": Range(start=6000, end=6050),
              "languages": "en-gb, en-us",
              "correction_text": "Rephrase for better readability.",
          },
      ],
      "War and Peace.txt": [
          {
              "label_ref": "text_region_003",
              "coordinates": Range(start=3000, end=3050),
              "languages": "en-ca, en-gb",
              "correction_text": "Grammar correction required.",
          },
          {
              "label_ref": "text_region_004",
              "coordinates": Range(start=4000, end=4050),
              "languages": "en-ca",
              "correction_text": "Check for historical accuracy.",
          },
      ],
  }


  # Cache label rows after initialization
  label_row_map = {}

  # First initialize label rows in a bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for data_title in text_annotations.keys():
          label_rows = project.list_label_rows_v2(data_title_eq=data_title)
          assert label_rows is not None, f"Error: label rows retrieval failed for {data_title}."

          if not label_rows:
              print(f"Skipping: No label row found for {data_title}")
              continue

          label_row = label_rows[0]
          label_row.initialise_labels(bundle=bundle)

          # Cache the initialized label row for further use
          label_row_map[data_title] = label_row
          assert data_title in label_row_map, f"Error: Label row for {data_title} not cached correctly."

  # Apply annotations
  label_rows_to_save = []

  for data_title, annotations in text_annotations.items():
      label_row = label_row_map.get(data_title)
      assert label_row is not None, f"Error: No initialized label row found for {data_title}."

      for annotation in annotations:
          selected_languages = annotation.get("languages", "").split(", ")
          assert selected_languages, (
              f"Error: No languages specified for annotation with label_ref {annotation['label_ref']}."
          )

          # Create Object Instance for English corrections if applicable
          if any(lang in ["en-ca", "en-gb", "en-us"] for lang in selected_languages):
              english_instance: ObjectInstance = text_object.create_instance()
              assert english_instance is not None, (
                  f"Error: Failed to create ObjectInstance for English corrections for {annotation['label_ref']}."
              )

              english_instance.set_for_frames(
                  frames=0,
                  coordinates=TextCoordinates(range=[annotation["coordinates"]]),
              )
              assert english_instance.frames == 0, (
                  f"Error: Frames not correctly set for English instance of {annotation['label_ref']}."
              )
              assert english_instance.coordinates.range == [annotation["coordinates"]], (
                  f"Error: Coordinates not correctly set for English instance of {annotation['label_ref']}."
              )

              english_instance.set_answer(attribute=correction_radio_attribute, answer=english_correction_option)
              assert english_instance.get_answer(correction_radio_attribute) == english_correction_option, (
                  "Error: English correction option not set correctly."
              )

              english_selected_options = [
                  option
                  for lang, option in {"en-ca": en_ca_option, "en-gb": en_gb_option, "en-us": en_us_option}.items()
                  if lang in selected_languages
              ]
              assert english_selected_options, (
                  f"Error: No options selected for English corrections for {annotation['label_ref']}."
              )

              if english_checklist_attribute and english_selected_options:
                  english_instance.set_answer(attribute=english_checklist_attribute, answer=english_selected_options)

              english_instance.set_answer(
                  attribute=english_correction_text_attribute, answer=annotation["correction_text"]
              )
              label_row.add_object_instance(english_instance)

          # Create Object Instance for Chinese corrections if applicable
          if any(lang in ["zh-tw", "zh-hk"] for lang in selected_languages):
              chinese_instance: ObjectInstance = text_object.create_instance()
              assert chinese_instance is not None, (
                  f"Error: Failed to create ObjectInstance for Chinese corrections for {annotation['label_ref']}."
              )

              chinese_instance.set_for_frames(
                  frames=0,
                  coordinates=TextCoordinates(range=[annotation["coordinates"]]),
              )
              assert chinese_instance.frames == 0, (
                  f"Error: Frames not correctly set for Chinese instance of {annotation['label_ref']}."
              )
              assert chinese_instance.coordinates.range == [annotation["coordinates"]], (
                  f"Error: Coordinates not correctly set for Chinese instance of {annotation['label_ref']}."
              )

              chinese_instance.set_answer(attribute=correction_radio_attribute, answer=chinese_correction_option)
              assert chinese_instance.get_answer(correction_radio_attribute) == chinese_correction_option, (
                  "Error: Chinese correction option not set correctly."
              )

              chinese_selected_options = [
                  option
                  for lang, option in {"zh-tw": zh_tw_option, "zh-hk": zh_hk_option}.items()
                  if lang in selected_languages
              ]
              assert chinese_selected_options, (
                  f"Error: No options selected for Chinese corrections for {annotation['label_ref']}."
              )

              if chinese_checklist_attribute and chinese_selected_options:
                  chinese_instance.set_answer(attribute=chinese_checklist_attribute, answer=chinese_selected_options)

              chinese_instance.set_answer(
                  attribute=chinese_correction_text_attribute, answer=annotation["correction_text"]
              )
              label_row.add_object_instance(chinese_instance)

          print(f"Added text region {annotation['label_ref']} to {data_title}")

      label_rows_to_save.append(label_row)

  # Save changes using a bundle
  with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
      for label_row in label_rows_to_save:
          assert label_row is not None, "Error: Label row to save is None."
          label_row.save(bundle=bundle)
          print(f"Saved label row for {label_row.data_title}")

  print("Multiple labels with manually provided correction text applied successfully!")

  ```
</CodeGroup>

## Import Classifications to Text Files

The example for the Classification uses nested attributes with the Ontology structure as follows:

* Accurate?
  * Yes
  * No
    * Correction (text field to provide edits for the correction)

<Note>`create_instance` must use `range_only=True` for text documents. This includes HTML documents.</Note>

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from typing import List
  from pathlib import Path
  from encord import EncordUserClient, Project
  from encord.objects.frames import Range
  from encord.objects import LabelRowV2, Classification, Option, OntologyStructure

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

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

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

  # Specify the data unit to apply classification
  label_row = project.list_label_rows_v2(
      data_title_eq="<file-name-for-text-file>.html"
  )[0]


  # Download the existing labels 
  label_row.initialise_labels()

  # Get the Ontology structure
  ontology_structure: OntologyStructure = label_row.ontology_structure

  # Assume that the following radio button classification exists in the Ontology.
  radio_ontology_classification: Classification = (
      ontology_structure.get_child_by_title(
          title="<classification-name>", type_=Classification
      )
  )

  radio_classification_option = radio_ontology_classification.get_child_by_title(
  title="<option-name>",
  type_=Option
  )

  # Create classification instance. `range_only=True` is required for HTML documents
  radio_classification_instance = radio_ontology_classification.create_instance(range_only=True)

  # Set the answer of the classification instance
  radio_classification_instance.set_answer(radio_classification_option)

  # Select the frames where the classification instance is present. Not required for global classifications
  radio_classification_instance.set_for_frames(frames=0)

  # Add it to the label row
  label_row.add_classification_instance(radio_classification_instance)

  # Save labels
  label_row.save()

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from __future__ import annotations
  from pathlib import Path
  from encord import EncordUserClient, Project
  from encord.objects import (
      Classification,
      OntologyStructure,
      LabelRowV2,
      TextAttribute,
      RadioAttribute,
      Option
  )
  from encord.objects.frames import Range

  SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID = "8a321a14-5f76-4a12-961b-3b1f2da932gk"

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

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

  # Specify the data unit to apply classification
  label_row = project.list_label_rows_v2(
      data_title_eq="My Text File.txt"
  )[0]

  label_row.initialise_labels()

  ontology_structure: OntologyStructure = label_row.ontology_structure

  # Get the parent classification
  text_ontology_classification = ontology_structure.get_child_by_title(
      title="Accurate?", type_=Classification
  )

  # Create an instance of the radio button classification
  text_classification_instance = text_ontology_classification.create_instance(range_only=True)

  # Get the radio button attribute and option
  accurate_radio_attribute = text_ontology_classification.get_child_by_title("Accurate?", type_=RadioAttribute)
  not_accurate_option = text_ontology_classification.get_child_by_title(title="No", type_=Option)

  # Set the answer for the radio button
  text_classification_instance.set_answer(attribute=accurate_radio_attribute, answer=not_accurate_option)

  # Get the nested attribute "Correction"
  correction_attribute = text_ontology_classification.get_child_by_title("Correction", type_=TextAttribute)

  # Set the text for the nested attribute
  text_classification_instance.set_answer(attribute=correction_attribute, answer="This page needs to be updated.")

  # Set the classification (for text documents) for the entire file
  text_classification_instance.set_for_frames(frames=0)

  # Add the classification instance to the label row
  label_row.add_classification_instance(text_classification_instance)

  # Save the label row
  label_row.save()

  ```
</CodeGroup>

## Export Labels for Text Files

<CodeGroup>
  ```python Template theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  import json

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

  # Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]

  # Download label information for the specific data unit
  specific_label_row.initialise_labels()

  # Print the labels as JSON
  print(json.dumps(specific_label_row.to_encord_dict()))

  ```

  ```python Example theme={"dark"}

  # Import dependencies
  from encord import EncordUserClient
  import json

  SSH_PATH= "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID= "7a321a15-5f76-4a12-961b-2b1f2da932bb"
  DATA_UNIT_NAME= "My Text File.txt"

  # Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]

  # Download label information for the specific data unit
  specific_label_row.initialise_labels()

  # Print the labels as JSON
  print(json.dumps(specific_label_row.to_encord_dict()))

  ```
</CodeGroup>

## Remove Labels from Text Files

<CodeGroup>
  ```python Template theme={"dark"}

  from encord import EncordUserClient
  import json

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

  # Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]


  object_to_remove = None
  specific_label_row.initialise_labels()
  for object_instance in specific_label_row.get_object_instances():
      if object_instance.object_hash == '<label-unique-id>':
          object_to_remove = object_instance

  specific_label_row.remove_object(object_to_remove)

  specific_label_row.save()


  ```

  ```python Example theme={"dark"}

  from encord import EncordUserClient
  import json

  SSH_PATH= "/Users/chris-encord/sdk-ssh-private-key.txt"
  PROJECT_ID= "7v321a15-5f76-4a12-961b-2b1f2da932bb"
  DATA_UNIT_NAME= "My Text File.txt"

  # Instantiate client. Replace <private_key_path> with the path to the file containing your private key.
  user_client = EncordUserClient.create_with_ssh_private_key(
      ssh_private_key_path=SSH_PATH
  )

  # Specify Project. Replace <project_hash> with the hash of the Project you want to export labels for.
  project = user_client.get_project(PROJECT_ID)

  # Specify the data unit you want to export labels for. Replace <file_name> with the name of your specific data unit.
  specific_label_row = project.list_label_rows_v2(
      data_title_eq=DATA_UNIT_NAME
  )[0]


  object_to_remove = None
  specific_label_row.initialise_labels()
  for object_instance in specific_label_row.get_object_instances():
      if object_instance.object_hash == 'dH3DrglO':
          object_to_remove = object_instance

  specific_label_row.remove_object(object_to_remove)

  specific_label_row.save()

  ```
</CodeGroup>


# PDF
Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-pdf-labels-classifications



PDFs support annotation using bounding box, polygon, and bitmask object labels and classifications. Using the Encord SDK you can import labels and classifications directly to PDFs that already exist in an Annotate Project. You can also use the SDK to view labels and classifications that exist on a PDF.

## Bounding Boxes and PDFs

The following screenshot provides the Ontology used with the code example.

<div>
  <img />
</div>

<Accordion title="Bounding Boxes">
  ```python Bounding Boxes and PDFs theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient, Project
  from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
  from encord.objects.coordinates import BoundingBoxCoordinates

  # SSH and Project details
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "12f1ebfb-bfdc-4682-a82b-bc20e5e01416"

  # Create user client
  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
  project: Project = user_client.get_project(PROJECT_ID)
  ontology_structure = project.ontology_structure

  # Get ontology object
  box_ontology_object: Object = ontology_structure.get_child_by_title(title="PDF BB", type_=Object)

  # Define radio attribute for correction types
  correction_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Corrections BB")
  english_correction_option = correction_radio_attribute.get_child_by_title(type_=Option, title="English corrections")
  chinese_correction_option = correction_radio_attribute.get_child_by_title(type_=Option, title="繁體中文修正")

  # Define checklist attributes
  english_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="English")
  en_ca_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-ca")
  en_gb_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-gb")
  en_us_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-us")

  chinese_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="繁體中文")
  zh_tw_option = chinese_checklist_attribute.get_child_by_title(type_=Option, title="zh-tw")
  zh_hk_option = chinese_checklist_attribute.get_child_by_title(type_=Option, title="zh-hk")

  # Define text attributes
  english_correction_text_attribute = ontology_structure.get_child_by_title(type_=TextAttribute, title="Correction text")
  chinese_correction_text_attribute = ontology_structure.get_child_by_title(type_=TextAttribute, title="更正")

  # Example label data (you can adjust this)
  pdf_labels = {
      "the-iliad.pdf": {
          # Specify the page number in the PDF. In the example below, page number 103 is labeled
          103: {
              "label_ref": "pdf_label_001",
              "coordinates": BoundingBoxCoordinates(height=0.4, width=0.4, top_left_x=0.1, top_left_y=0.1),
              "correction_type": "English corrections",
              "checklist_options": "en-ca, en-gb",
              "text_correction": "Fixed typo in English text.",
          }
      },
      "dracula.pdf": {
          # Specify the page number in the PDF. In the example below, page number 17 is labeled
          17: {
              "label_ref": "pdf_label_002",
              "coordinates": BoundingBoxCoordinates(height=0.3, width=0.5, top_left_x=0.2, top_left_y=0.2),
              "correction_type": "繁體中文修正",
              "checklist_options": "zh-tw",
              "text_correction": "修正了中文繁體的標點符號。",
          }
      }
  }

  # Loop through each data unit (image, video, etc.)
  for data_unit, frame_coordinates in pdf_labels.items():
      object_instances_by_label_ref = {}

      # Get the label row for the current data unit
      label_row = project.list_label_rows_v2(data_title_eq=data_unit)[0]
      label_row.initialise_labels()

      # Loop through the frames for the current data unit
      for frame_number, items in frame_coordinates.items():
          if not isinstance(items, list):  # Single or multiple objects in the frame
              items = [items]

          for item in items:
              label_ref = item["label_ref"]
              coord = item["coordinates"]
              correction_type = item["correction_type"]
              checklist_options_str = item.get("checklist_options", "")
              text_correction = item.get("text_correction", "")

              # Check if label_ref already exists for reusability
              if label_ref not in object_instances_by_label_ref:
                  box_object_instance: ObjectInstance = box_ontology_object.create_instance()
                  object_instances_by_label_ref[label_ref] = box_object_instance  # Store for reuse

                  # Set correction type (radio attribute)
                  if correction_type == "English corrections":
                      box_object_instance.set_answer(attribute=correction_radio_attribute, answer=english_correction_option)

                      # Set checklist options for English
                      checklist_answers = []
                      for option in [opt.strip() for opt in checklist_options_str.split(",")]:
                          if option == "en-ca":
                              checklist_answers.append(en_ca_option)
                          elif option == "en-gb":
                              checklist_answers.append(en_gb_option)
                          elif option == "en-us":
                              checklist_answers.append(en_us_option)

                      if checklist_answers:
                          box_object_instance.set_answer(
                              attribute=english_checklist_attribute,
                              answer=checklist_answers,
                              overwrite=True,
                          )

                      # Set text correction
                      if text_correction:
                          box_object_instance.set_answer(attribute=english_correction_text_attribute, answer=text_correction)

                  elif correction_type == "繁體中文修正":
                      box_object_instance.set_answer(attribute=correction_radio_attribute, answer=chinese_correction_option)

                      # Set checklist options for Chinese
                      checklist_answers = []
                      for option in [opt.strip() for opt in checklist_options_str.split(",")]:
                          if option == "zh-tw":
                              checklist_answers.append(zh_tw_option)
                          elif option == "zh-hk":
                              checklist_answers.append(zh_hk_option)

                      if checklist_answers:
                          box_object_instance.set_answer(
                              attribute=chinese_checklist_attribute,
                              answer=checklist_answers,
                              overwrite=True,
                          )

                      # Set text correction
                      if text_correction:
                          box_object_instance.set_answer(attribute=chinese_correction_text_attribute, answer=text_correction)

              else:
                  # Reuse existing instance across frames
                  box_object_instance = object_instances_by_label_ref[label_ref]

              # Assign the object to the frame and track it
              box_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

      # Add object instances to label_row **only if they have frames assigned**
      for box_object_instance in object_instances_by_label_ref.values():
          if box_object_instance.get_annotation_frames():  # Ensures it has at least one frame
              label_row.add_object_instance(box_object_instance)

      # Upload all labels for this data unit (video/image) to the server
      label_row.save()

  print("Labels with English and Mandarin corrections have been added for all data units.")

  ```
</Accordion>

## Polygons and PDFs

Polygons offer a number of options when labeling PDFs.

Polygons can have simple and complex shapes, including being enclosed in one another, and encompassing separate regions. In each case the polygon's coordinates are arranged in a different way.

To specify coordinates for polygons use the following format:

<CodeGroup>
  ```python Simple theme={"dark"}

  PolygonCoordinates(polygons=[[[PointCoordinate(x1, y1), PointCoordinate(x2, y2),...]]]

  ```

  ```python Donut theme={"dark"}

  PolygonCoordinates(polygons=
  [
      [
          [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Outer ring
          [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Inner ring
      ]
  ]

  ```

  ```python Multiple Polygons theme={"dark"}

  PolygonCoordinates(polygons=
  [
      [
          [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 1
      ],
      [
          [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 2
      ],
      [
          [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon 3
      ],

  ]

  ```

  ```python Donut with Object Inside theme={"dark"}

  PolygonCoordinates(polygons=
  [
      [
          [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Outer ring
          [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Inner ring
      ],
      [
          [PointCoordinate(x1, y1), PointCoordinate(x2, y2),...], # Polygon inside
      ],

  ]

  ```
</CodeGroup>

<Info>
  For more information on polygon labels [go here](/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual#polygons-advanced)
</Info>

This example uses multiple polygons to label the PDF.

The following screenshot provides the Ontology used with the code example.

<div>
  <img />
</div>

<Accordion title="Polygons">
  ```python Polygons and PDFs theme={"dark"}
  # Import dependencies
  from encord import EncordUserClient, Project
  from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
  from encord.objects.coordinates import PolygonCoordinates, PointCoordinate

  # SSH and Project details
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "12f1ebfb-bfdc-4682-a82b-bc20e5e01416"

  # Create user client
  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
  project: Project = user_client.get_project(PROJECT_ID)
  ontology_structure = project.ontology_structure

  # Get ontology object
  polygon_ontology_object: Object = ontology_structure.get_child_by_title(title="PDF PG", type_=Object)

  # Define radio attribute for correction types
  correction_radio_attribute = ontology_structure.get_child_by_title(type_=RadioAttribute, title="Corrections PG")
  english_correction_option = correction_radio_attribute.get_child_by_title(type_=Option, title="English corrections")
  chinese_correction_option = correction_radio_attribute.get_child_by_title(type_=Option, title="繁體中文修正")

  # Define checklist attributes
  english_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="English")
  en_ca_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-ca")
  en_gb_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-gb")
  en_us_option = english_checklist_attribute.get_child_by_title(type_=Option, title="en-us")

  chinese_checklist_attribute = ontology_structure.get_child_by_title(type_=ChecklistAttribute, title="繁體中文")
  zh_tw_option = chinese_checklist_attribute.get_child_by_title(type_=Option, title="zh-tw")
  zh_hk_option = chinese_checklist_attribute.get_child_by_title(type_=Option, title="zh-hk")

  # Define text attributes
  english_correction_text_attribute = ontology_structure.get_child_by_title(type_=TextAttribute, title="Correction text")
  chinese_correction_text_attribute = ontology_structure.get_child_by_title(type_=TextAttribute, title="更正")

  # Example label data (you can adjust this)
  pdf_labels = {
      "the-iliad.pdf": {
          # Specify the page number in the PDF. In the example below, page number 103 is labeled
          103: {
              "label_ref": "pdf_label_001",
              "coordinates": PolygonCoordinates(polygons=[
                  [
                      # First rectangle
                      [
                          PointCoordinate(0.1, 0.1),
                          PointCoordinate(0.4, 0.1),
                          PointCoordinate(0.4, 0.3),
                          PointCoordinate(0.1, 0.3),
                          PointCoordinate(0.1, 0.1)  # Close the polygon
                      ]
                  ],
                  [
                      # Second rectangle
                      [
                          PointCoordinate(0.5, 0.5),
                          PointCoordinate(0.7, 0.5),
                          PointCoordinate(0.7, 0.7),
                          PointCoordinate(0.5, 0.7),
                          PointCoordinate(0.5, 0.5)  # Close the polygon
                      ]
                  ],
              ]),
              "correction_type": "English corrections",
              "checklist_options": "en-ca, en-gb",
              "text_correction": "Fixed typo in English text.",
          }
      },
      "dracula.pdf": {
          # Specify the page number in the PDF. In the example below, page number 17 is labeled
          17: {
              "label_ref": "pdf_label_002",
              "coordinates": PolygonCoordinates(polygons=[
                  [
                      # First rectangle
                      [
                          PointCoordinate(0.2, 0.2),
                          PointCoordinate(0.5, 0.2),
                          PointCoordinate(0.5, 0.4),
                          PointCoordinate(0.2, 0.4),
                          PointCoordinate(0.2, 0.2)  # Close the polygon
                      ]
                  ],
                  [
                      # Second rectangle
                      [
                          PointCoordinate(0.6, 0.6),
                          PointCoordinate(0.8, 0.6),
                          PointCoordinate(0.8, 0.8),
                          PointCoordinate(0.6, 0.8),
                          PointCoordinate(0.6, 0.6)  # Close the polygon
                      ]
                  ],
              ]),
              "correction_type": "繁體中文修正",
              "checklist_options": "zh-tw",
              "text_correction": "修正了中文繁體的標點符號。",
          }
      }
  }

  # Loop through each data unit (image, video, etc.)
  for data_unit, frame_coordinates in pdf_labels.items():
      object_instances_by_label_ref = {}

      # Get the label row for the current data unit
      label_row = project.list_label_rows_v2(data_title_eq=data_unit)[0]
      label_row.initialise_labels()

      # Loop through the frames for the current data unit
      for frame_number, items in frame_coordinates.items():
          if not isinstance(items, list):  # Single or multiple objects
              items = [items]

          for item in items:
              label_ref = item["label_ref"]
              coord = item["coordinates"]
              correction_type = item["correction_type"]
              checklist_options_str = item.get("checklist_options", "")
              text_correction = item.get("text_correction", "")

              # Check if label_ref already exists for reusability
              if label_ref not in object_instances_by_label_ref:
                  polygon_object_instance: ObjectInstance = polygon_ontology_object.create_instance()
                  object_instances_by_label_ref[label_ref] = polygon_object_instance  # Store for reuse

                  # Set correction type (radio attribute)
                  if correction_type == "English corrections":
                      polygon_object_instance.set_answer(attribute=correction_radio_attribute, answer=english_correction_option)

                      # Set checklist options for English
                      checklist_answers = []
                      for option in [opt.strip() for opt in checklist_options_str.split(",")]:
                          if option == "en-ca":
                              checklist_answers.append(en_ca_option)
                          elif option == "en-gb":
                              checklist_answers.append(en_gb_option)
                          elif option == "en-us":
                              checklist_answers.append(en_us_option)

                      if checklist_answers:
                          polygon_object_instance.set_answer(
                              attribute=english_checklist_attribute,
                              answer=checklist_answers,
                              overwrite=True,
                          )

                      # Set text correction
                      if text_correction:
                          polygon_object_instance.set_answer(attribute=english_correction_text_attribute, answer=text_correction)

                  elif correction_type == "繁體中文修正":
                      polygon_object_instance.set_answer(attribute=correction_radio_attribute, answer=chinese_correction_option)

                      # Set checklist options for Chinese
                      checklist_answers = []
                      for option in [opt.strip() for opt in checklist_options_str.split(",")]:
                          if option == "zh-tw":
                              checklist_answers.append(zh_tw_option)
                          elif option == "zh-hk":
                              checklist_answers.append(zh_hk_option)

                      if checklist_answers:
                          polygon_object_instance.set_answer(
                              attribute=chinese_checklist_attribute,
                              answer=checklist_answers,
                              overwrite=True,
                          )

                      # Set text correction
                      if text_correction:
                          polygon_object_instance.set_answer(attribute=chinese_correction_text_attribute, answer=text_correction)

              else:
                  # Reuse existing instance across frames
                  polygon_object_instance = object_instances_by_label_ref[label_ref]

              # Assign the object to the frame and track it
              polygon_object_instance.set_for_frames(coordinates=coord, frames=frame_number)

      # Add object instances to label_row **only if they have frames assigned**
      for polygon_object_instance in object_instances_by_label_ref.values():
          if polygon_object_instance.get_annotation_frames():  # Ensures it has at least one frame
              label_row.add_object_instance(polygon_object_instance)

      # Upload all labels for this data unit (video/image) to the server
      label_row.save()

  print("Labels with English and Mandarin corrections have been added for all data units.")

  ```
</Accordion>

## Classifications with PDFs

The following screenshot provides the Ontology used with the code example.

<div>
  <img />
</div>

<Accordion title="Classifications">
  ```python Classifications and PDFs theme={"dark"}
  # Import dependencies
  from pathlib import Path
  from encord import EncordUserClient
  from encord.objects import Classification, Option

  # Configuration
  SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
  PROJECT_ID = "9ae72230-c686-484b-a6b9-9ed631c6dce8"

  # Create user client using access key
  user_client = 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
  project = user_client.get_project(PROJECT_ID)

  # Define specific configurations for each data unit
  data_unit_configs = [
      {
          "title": "anne-of-green-gables.pdf",
          "classifications": [
              {
                  "name": "Accuracy",
                  "type": "radio",
                  "option": "5",
                  "frame_range": (10, 20)
              },
              {
                  "name": "Doc qualities",
                  "type": "checklist",
                  "options": ["Clarity", "Engaging"],
                  "frame_range": (15, 25)
              }
          ]
      },
      {
          "title": "the-legend-of-sleepy-hollow.pdf",
          "classifications": [
              {
                  "name": "Accuracy",
                  "type": "radio",
                  "option": "3",
                  "frame_range": (5, 15)
              },
              {
                  "name": "Edit",
                  "type": "text",
                  "text": "Needs more context",
                  "frame_range": (3, 10)
              }
          ]
      },
      {
          "title": "the-iliad.pdf",
          "classifications": [
              {
                  "name": "Doc qualities",
                  "type": "checklist",
                  "options": ["Logical structure", "Audience focused"],
                  "frame_range": (30, 40)
              }
          ]
      }
  ]

  # Process each data unit with its specific configurations
  for config in data_unit_configs:
      try:
          # Get the label row for the specific data unit
          label_rows = project.list_label_rows_v2(
              data_title_eq=config["title"]
          )
          
          if not label_rows:
              print(f"No label row found for {config['title']}, skipping...")
              continue
              
          label_row = label_rows[0]

          # Download the existing labels
          label_row.initialise_labels()
          
          # Get the ontology structure
          ontology_structure = label_row.ontology_structure
          
          # Process each classification for this data unit
          for classification_config in config["classifications"]:
              # Find the classification in the ontology
              classification = ontology_structure.get_child_by_title(
                  title=classification_config["name"],
                  type_=Classification
              )
              
              # Create classification instance
              classification_instance = classification.create_instance()
              
              # Set the answer based on classification type
              if classification_config["type"] == "radio":
                  # For radio button classification
                  option = classification.get_child_by_title(
                      title=classification_config["option"],
                      type_=Option
                  )
                  classification_instance.set_answer(option)
                  
              elif classification_config["type"] == "checklist":
                  # For checklist classification
                  options = []
                  for option_name in classification_config["options"]:
                      option = classification.get_child_by_title(
                          title=option_name,
                          type_=Option
                      )
                      options.append(option)
                  classification_instance.set_answer(options)
                  
              elif classification_config["type"] == "text":
                  # For text classification
                  classification_instance.set_answer(answer=classification_config["text"])
              
              # Apply to the specified frame range
              start_frame, end_frame = classification_config["frame_range"]
              for frame in range(start_frame, end_frame + 1):
                  classification_instance.set_for_frames(
                      frames=frame,
                      manual_annotation=True,
                      confidence=1.0
                  )
              
              # Add to label row
              label_row.add_classification_instance(classification_instance)
          
          # Save the changes
          label_row.save()
          print(f"Classifications successfully applied to {config['title']}")
      
      except Exception as e:
          print(f"Error processing {config['title']}: {e}")

  ```
</Accordion>


# Beta.scene.builder
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.builder



Builder API for constructing Encord scene payloads.

Provides a multi-stage builder pattern for assembling scene data. Each stream
type has its own nested builder, and event timestamps are assigned sequentially.

**Stages:**

1. Create a [SceneBuilder](/sdk-documentation/sdk-references/beta.scene.builder#scenebuilder-objects) and (optionally) configure global settings.
2. Add one or more streams -- each `add_*_stream` call returns a nested
   stream builder.
3. Populate event streams via the stream-specific method
   (`add_pcd`, `add_image`, `add_camera_params`, `add_pose`), or
   provide the CSV URI when creating a time-series stream.
4. Pass the builder to SDK upload/create methods, which validates and
   serializes internally.

Every mutator returns `self`, so stream-local calls can be chained fluently::

scene = SceneBuilder()
scene.add\_pcd\_stream("lidar").add\_pcd(uri="s3://bucket/frame0.pcd")

## SceneBuilder Objects

```python theme={"dark"}
class SceneBuilder()
```

Top-level builder for constructing an Encord scene payload.

Supported stream types:

* **Point cloud** -- [add\_pcd\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_pcd_stream)
* **Camera parameters** -- [add\_camera\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_camera_stream)
* **Frame of reference** -- [add\_for\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_for_stream)
* **Image** -- [add\_image\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_image_stream)
* **Time series** -- [add\_time\_series\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_time_series_stream)

Stream names must be unique.  Reusing a name raises an error.

The scene must contain at least one point-cloud or image stream, and every
event stream must have at least one event. `_build` validates and
serializes builders internally for SDK upload/create methods.

#### set\_world\_convention

```python theme={"dark"}
def set_world_convention(*, x: Direction, y: Direction,
                         z: Direction) -> SceneBuilder
```

Set the world coordinate-system convention.

The three directions must map to three distinct spatial axes,
forming a valid orthogonal coordinate system.  The convention's
handedness (right-handed when `cross(x, y) == z`) **must match**
the camera convention.

Available directions: `Direction.UP`, `Direction.DOWN`,
`Direction.LEFT`, `Direction.RIGHT`, `Direction.FORWARD`,
`Direction.BACKWARD`.

#### set\_camera\_convention

```python theme={"dark"}
def set_camera_convention(*, x: Direction, y: Direction,
                          z: Direction) -> SceneBuilder
```

Set the camera coordinate-system convention.

The three directions must map to three distinct spatial axes,
forming a valid orthogonal coordinate system.  The convention's
handedness **must match** the world convention.

Available directions: `Direction.UP`, `Direction.DOWN`,
`Direction.LEFT`, `Direction.RIGHT`, `Direction.FORWARD`,
`Direction.BACKWARD`.

#### add\_time\_series\_stream

```python theme={"dark"}
def add_time_series_stream(name: str, *, uri: str) -> TimeSeriesStreamBuilder
```

Add a self-contained CSV time-series stream.

**Arguments**:

* `name` - Unique stream name.
* `uri` - Non-empty URI pointing to the CSV file.

#### add\_pcd\_stream

```python theme={"dark"}
def add_pcd_stream(name: str,
                   *,
                   frame_of_reference: str | FoRStreamBuilder | None = None,
                   pose: Pose | None = None) -> PCDStreamBuilder
```

Add a point-cloud stream.

**Arguments**:

* `name` - Unique stream name.
* `frame_of_reference` - Optional FoR stream to link to.
* `pose` - Optional static pose for the sensor mount.

#### add\_camera\_stream

```python theme={"dark"}
def add_camera_stream(name: str,
                      *,
                      frame_of_reference: str | FoRStreamBuilder | None = None,
                      pose: Pose | None = None) -> CameraStreamBuilder
```

Add a camera-parameters stream.

**Arguments**:

* `name` - Unique stream name.
* `frame_of_reference` - Optional FoR stream to link to.
* `pose` - Optional static pose for the sensor mount.

#### add\_for\_stream

```python theme={"dark"}
def add_for_stream(name: str,
                   *,
                   parent_for_id: str | FoRStreamBuilder | None = None
                   ) -> FoRStreamBuilder
```

Add a frame-of-reference stream.

**Arguments**:

* `name` - Unique stream name.  Other streams reference this
  stream via this name.
* `parent_for_id` - Optional parent FoR -- either the **stream name**
  or a [FoRStreamBuilder](/sdk-documentation/sdk-references/beta.scene.stream#forstreambuilder-objects). If omitted, the stream is
  attached to the scene root.

#### add\_image\_stream

```python theme={"dark"}
def add_image_stream(name: str,
                     *,
                     camera: str | None = None,
                     width: int | None = None,
                     height: int | None = None,
                     intrinsics: Intrinsics | None = None,
                     timestamp: float | None = None,
                     frame_of_reference: str | FoRStreamBuilder | None = None,
                     pose: Pose | None = None) -> ImageStreamBuilder
```

Add an image stream.

There are two modes:

1. **Existing camera**: pass `camera="cam_stream_name"` to link
   to an already-registered camera stream.
2. **Inline camera**: pass `width`, `height`, and `intrinsics`
   to auto-create a camera stream named `{name}/camera`.

**Arguments**:

* `name` - Unique stream name.
* `camera` - The **stream name** of a camera-parameters stream.
  Mutually exclusive with `width`/`height`/`intrinsics`.
* `width` - Image width in pixels (inline camera mode).
* `height` - Image height in pixels (inline camera mode).
* `intrinsics` - Camera intrinsics (inline camera mode).
* `timestamp` - Camera-parameters event timestamp (inline camera mode).
* `frame_of_reference` - Optional FoR linkage for the auto-created
  camera stream (only used in inline camera mode).
* `pose` - Optional static pose for the auto-created camera stream
  (only used in inline camera mode).


# Beta.scene.internal.common
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.internal.common



Shared types used by both import\_internal and read\_internal.

Contains: snake2camel, CamelModelApi, Direction, Convention, SelfContainedFormat, and all distortion models.

## SelfContainedFormat Objects

```python theme={"dark"}
class SelfContainedFormat(str, Enum)
```

#### BAG

ROS 1

#### DB3

ROS 2


# Beta.scene.internal.scene
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.internal.scene



Read-side composite scene models returned by GET /v2/public/scene/.

These mirror the backend's external API models from ml-utils and are used to
deserialize the response for [SceneReader](/sdk-documentation/sdk-references/beta.scene.reader#scenereader-objects).

## URIEvent Objects

```python theme={"dark"}
@dataclass
class URIEvent()
```

An event with both the raw URI and a signed download URL.

## SceneResponse Objects

```python theme={"dark"}
class SceneResponse(RootModelDTO[Scene])
```

Wrapper so the API client can deserialize the discriminated Scene union.


# Beta.scene.internal.upload
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.internal.upload



Pydantic models for InputScene with all dependencies inlined.

Shared types (Convention, Direction, distortion models, SelfContainedFormat) live in common\_internal.

## InputAffineTransform Objects

```python theme={"dark"}
class InputAffineTransform(RootModel[tuple[
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
        float,
]])
```

#### validate\_affine\_matrix

```python theme={"dark"}
@model_validator(mode="after")
def validate_affine_matrix() -> InputAffineTransform
```

Validate that the matrix is a proper affine matrix (orthogonal with det=1) & only translation


# Beta.scene.intrinsics
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.intrinsics



Public camera intrinsics types and convenience constructors.

## SimpleIntrinsics Objects

```python theme={"dark"}
@dataclass
class SimpleIntrinsics()
```

Simple camera intrinsics (focal length + principal point).

Prefer the dedicated constructors ([intrinsics\_pinhole()](/sdk-documentation/sdk-references/beta.scene.intrinsics#intrinsics_pinhole),
[intrinsics\_radial()](/sdk-documentation/sdk-references/beta.scene.intrinsics#intrinsics_radial), [intrinsics\_plumb\_bob()](/sdk-documentation/sdk-references/beta.scene.intrinsics#intrinsics_plumb_bob),
[intrinsics\_fisheye()](/sdk-documentation/sdk-references/beta.scene.intrinsics#intrinsics_fisheye)) or the generic [intrinsics\_simple()](/sdk-documentation/sdk-references/beta.scene.intrinsics#intrinsics_simple)
rather than instantiating this class directly.

The `extra` dict holds distortion coefficients and optional fields.
Distortion coefficients are model-specific. The following optional
fields apply to all models: `dfx`, `dfy`, `dox`, `doy`, `skew`.

## AdvancedIntrinsics Objects

```python theme={"dark"}
@dataclass
class AdvancedIntrinsics()
```

Advanced camera intrinsics (full calibration matrices).

.. warning::
In most cases [SimpleIntrinsics](/sdk-documentation/sdk-references/beta.scene.intrinsics#simpleintrinsics-objects) (via
[intrinsics\_simple()](/sdk-documentation/sdk-references/beta.scene.intrinsics#intrinsics_simple) or one of the dedicated constructors)
is sufficient and much easier to work with. Only use advanced
intrinsics when you have pre-computed full K / R / P calibration
matrices and genuinely need to supply them directly.

Prefer [intrinsics\_advanced()](/sdk-documentation/sdk-references/beta.scene.intrinsics#intrinsics_advanced) rather than instantiating this
class directly.

**Arguments**:

* `k` - 9-element intrinsic camera matrix (row-major 3x3).
  Validated to have exactly 9 elements at build time.
* `r` - 9-element rectification matrix (row-major 3x3).
  Validated to have exactly 9 elements at build time.
* `p` - 12-element projection matrix (row-major 3x4).
  Validated to have exactly 12 elements at build time.
* `model` - Optional distortion model name.

#### intrinsics\_simple

```python theme={"dark"}
def intrinsics_simple(fx: float,
                      fy: float,
                      ox: float,
                      oy: float,
                      *,
                      model: str | None = None,
                      **kwargs: float) -> SimpleIntrinsics
```

Build simple camera intrinsics (focal length + principal point).

For models without a dedicated constructor, pass the model name and
its coefficients as keyword arguments::

intrinsics\_simple(fx, fy, ox, oy, model="division", k=0.01)
intrinsics\_simple(fx, fy, ox, oy, model="ucm", xi=0.5, k1=0.1, k2=0.0, k3=0.0)

**Arguments**:

* `fx` - Focal length along the *x*-axis (pixels).
* `fy` - Focal length along the *y*-axis (pixels).
* `ox` - Principal-point *x* offset (pixels).
* `oy` - Principal-point *y* offset (pixels).
* `model` - Optional distortion model name.
* `**kwargs` - Distortion coefficients and optional extra fields.

#### intrinsics\_advanced

```python theme={"dark"}
def intrinsics_advanced(k: Sequence[float] | None = None,
                        r: Sequence[float] | None = None,
                        p: Sequence[float] | None = None,
                        *,
                        model: str | None = None) -> AdvancedIntrinsics
```

Build advanced camera intrinsics using full calibration matrices.

.. warning::
In most cases [intrinsics\_simple()](/sdk-documentation/sdk-references/beta.scene.intrinsics#intrinsics_simple) (or one of the dedicated
constructors) is sufficient. Only reach for advanced intrinsics
when you have pre-computed K / R / P matrices.

**Arguments**:

* `k` - 9-element intrinsic camera matrix (row-major 3x3).
* `r` - 9-element rectification matrix (row-major 3x3).
* `p` - 12-element projection matrix (row-major 3x4).
* `model` - Optional distortion model name.

#### intrinsics\_pinhole

```python theme={"dark"}
def intrinsics_pinhole(fx: float, fy: float, ox: float,
                       oy: float) -> SimpleIntrinsics
```

Build pinhole intrinsics (no distortion coefficients).

**Arguments**:

* `fx` - Focal length along the *x*-axis (pixels).
* `fy` - Focal length along the *y*-axis (pixels).
* `ox` - Principal-point *x* offset (pixels).
* `oy` - Principal-point *y* offset (pixels).

#### intrinsics\_radial

```python theme={"dark"}
def intrinsics_radial(fx: float, fy: float, ox: float, oy: float, *, k1: float,
                      k2: float, k3: float) -> SimpleIntrinsics
```

Build intrinsics with a radial distortion model.

**Arguments**:

* `fx` - Focal length along the *x*-axis (pixels).
* `fy` - Focal length along the *y*-axis (pixels).
* `ox` - Principal-point *x* offset (pixels).
* `oy` - Principal-point *y* offset (pixels).
* `k1` - First radial distortion coefficient.
* `k2` - Second radial distortion coefficient.
* `k3` - Third radial distortion coefficient.

#### intrinsics\_plumb\_bob

```python theme={"dark"}
def intrinsics_plumb_bob(fx: float, fy: float, ox: float, oy: float, *,
                         k1: float, k2: float, k3: float, t1: float,
                         t2: float) -> SimpleIntrinsics
```

Build intrinsics with a plumb-bob (Brown-Conrady) distortion model.

**Arguments**:

* `fx` - Focal length along the *x*-axis (pixels).
* `fy` - Focal length along the *y*-axis (pixels).
* `ox` - Principal-point *x* offset (pixels).
* `oy` - Principal-point *y* offset (pixels).
* `k1` - First radial distortion coefficient.
* `k2` - Second radial distortion coefficient.
* `k3` - Third radial distortion coefficient.
* `t1` - First tangential distortion coefficient.
* `t2` - Second tangential distortion coefficient.

#### intrinsics\_fisheye

```python theme={"dark"}
def intrinsics_fisheye(fx: float, fy: float, ox: float, oy: float, *,
                       k1: float, k2: float, k3: float,
                       k4: float) -> SimpleIntrinsics
```

Build intrinsics with a fisheye (Kannala-Brandt) distortion model.

**Arguments**:

* `fx` - Focal length along the *x*-axis (pixels).
* `fy` - Focal length along the *y*-axis (pixels).
* `ox` - Principal-point *x* offset (pixels).
* `oy` - Principal-point *y* offset (pixels).
* `k1` - First distortion coefficient.
* `k2` - Second distortion coefficient.
* `k3` - Third distortion coefficient.
* `k4` - Fourth distortion coefficient.

#### intrinsics\_rational\_polynomial

```python theme={"dark"}
def intrinsics_rational_polynomial(fx: float, fy: float, ox: float, oy: float,
                                   *, k1: float, k2: float, k3: float,
                                   k4: float, k5: float, k6: float, t1: float,
                                   t2: float) -> SimpleIntrinsics
```

Build intrinsics with a rational-polynomial distortion model.

**Arguments**:

* `fx` - Focal length along the *x*-axis (pixels).
* `fy` - Focal length along the *y*-axis (pixels).
* `ox` - Principal-point *x* offset (pixels).
* `oy` - Principal-point *y* offset (pixels).
* `k1` - First radial distortion coefficient.
* `k2` - Second radial distortion coefficient.
* `k3` - Third radial distortion coefficient.
* `k4` - Fourth radial distortion coefficient.
* `k5` - Fifth radial distortion coefficient.
* `k6` - Sixth radial distortion coefficient.
* `t1` - First tangential distortion coefficient.
* `t2` - Second tangential distortion coefficient.

#### intrinsics\_cylindrical

```python theme={"dark"}
def intrinsics_cylindrical(fx: float, fy: float, ox: float,
                           oy: float) -> SimpleIntrinsics
```

Build intrinsics with a cylindrical distortion model (no coefficients).

**Arguments**:

* `fx` - Focal length along the *x*-axis (pixels).
* `fy` - Focal length along the *y*-axis (pixels).
* `ox` - Principal-point *x* offset (pixels).
* `oy` - Principal-point *y* offset (pixels).


# Beta.scene.pose
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.pose



Public pose types and convenience constructors.

## Position Objects

```python theme={"dark"}
@dataclass
class Position()
```

3-D position (translation).

## CompositePose Objects

```python theme={"dark"}
@dataclass
class CompositePose()
```

Rotation + position pair.

## AffinePose Objects

```python theme={"dark"}
@dataclass
class AffinePose()
```

4x4 affine transform matrix (16 floats, **column-major**).

The 16 values are stored column-by-column::

Given the matrix:
\| r00  r01  r02  tx |
\| r10  r11  r12  ty |
\| r20  r21  r22  tz |
\|  0    0    0    1 |

Flat order: \[r00, r10, r20, 0,
r01, r11, r21, 0,
r02, r12, r22, 0,
tx,  ty,  tz,  1]

The upper-left 3x3 must be a proper rotation matrix (orthogonal,
`det = 1`). The fourth column is translation and the fourth row
must be `[0, 0, 0, 1]`. These constraints are enforced server-side.

#### quaternion\_pose

```python theme={"dark"}
def quaternion_pose(qx: float, qy: float, qz: float, qw: float, x: float,
                    y: float, z: float) -> CompositePose
```

Create a pose from a unit quaternion rotation and a position.

The quaternion must have unit magnitude (server-side validated).
See [QuaternionRotation](/sdk-documentation/sdk-references/beta.scene.rotation#quaternionrotation-objects) for constraints.

**Arguments**:

* `qx` - Quaternion *x* component (in `[-1, 1]`).
* `qy` - Quaternion *y* component (in `[-1, 1]`).
* `qz` - Quaternion *z* component (in `[-1, 1]`).
* `qw` - Quaternion *w* (scalar) component (in `[-1, 1]`).
* `x` - Translation along the world *x*-axis.
* `y` - Translation along the world *y*-axis.
* `z` - Translation along the world *z*-axis.

#### euler\_pose

```python theme={"dark"}
def euler_pose(rx: float, ry: float, rz: float, x: float, y: float,
               z: float) -> CompositePose
```

Create a pose from Euler angles (radians) and a position.

Rotation order is extrinsic X-Y-Z. See [EulerRotation](/sdk-documentation/sdk-references/beta.scene.rotation#eulerrotation-objects) for
constraints.

**Arguments**:

* `rx` - Rotation around the *x*-axis in radians.
* `ry` - Rotation around the *y*-axis in radians.
* `rz` - Rotation around the *z*-axis in radians.
* `x` - Translation along the world *x*-axis.
* `y` - Translation along the world *y*-axis.
* `z` - Translation along the world *z*-axis.

#### matrix\_pose

```python theme={"dark"}
def matrix_pose(rotation: Sequence[float], x: float, y: float,
                z: float) -> CompositePose
```

Create a pose from a 3x3 rotation matrix and a position.

See [MatrixRotation](/sdk-documentation/sdk-references/beta.scene.rotation#matrixrotation-objects) for constraints (orthogonal, `det = 1`).

**Arguments**:

* `rotation` - Nine floats in **column-major** order representing a
  3x3 rotation matrix.
* `x` - Translation along the world *x*-axis.
* `y` - Translation along the world *y*-axis.
* `z` - Translation along the world *z*-axis.

#### affine\_transform

```python theme={"dark"}
def affine_transform(matrix: Sequence[float]) -> AffinePose
```

Create a pose from a 4x4 affine transform matrix.

See [AffinePose](/sdk-documentation/sdk-references/beta.scene.pose#affinepose-objects) for constraints (rotation submatrix must be
proper, bottom row `[0, 0, 0, 1]`).

**Arguments**:

* `matrix` - Sixteen floats in **column-major** order. The fourth
  row must be `[0, 0, 0, 1]`.

#### identity\_pose

```python theme={"dark"}
def identity_pose() -> CompositePose
```

Return the identity pose (no rotation, no translation).

#### translation\_only

```python theme={"dark"}
def translation_only(x: float, y: float, z: float) -> CompositePose
```

Create a pose with translation but no rotation.

**Arguments**:

* `x` - Translation along the world *x*-axis.
* `y` - Translation along the world *y*-axis.
* `z` - Translation along the world *z*-axis.

#### rotation\_only

```python theme={"dark"}
def rotation_only(rotation: Rotation) -> CompositePose
```

Create a pose with rotation but no translation.

**Arguments**:

* `rotation` - Any supported rotation type (quaternion, Euler, or
  matrix).


# Beta.scene.reader
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.reader



Public SDK scene read types.

These are stable SDK types that insulate users from the internal wire format.
They are constructed from the internal types in `beta/scene/internal/scene.py`.

## SceneEvent Objects

```python theme={"dark"}
@dataclass
class SceneEvent()
```

A single event in a stream, with its signed download URL and timestamp.

#### timestamp

Timestamp of the event.

#### url

Raw unsigned URI as stored in the scene definition.

#### signed\_url

Time-limited signed URL for downloading the file.

## PointCloudStream Objects

```python theme={"dark"}
@dataclass
class PointCloudStream()
```

A stream of lidar point cloud events.

#### find\_event

```python theme={"dark"}
def find_event(timestamp: float) -> SceneEvent | None
```

Return the event with the given timestamp, or `None` if not present.

#### get\_event

```python theme={"dark"}
def get_event(timestamp: float) -> SceneEvent
```

Return the event with the given timestamp.

**Raises**:

* `KeyError` - If no event with that timestamp exists.

## ImageStream Objects

```python theme={"dark"}
@dataclass
class ImageStream()
```

A stream of camera image events.

#### find\_event

```python theme={"dark"}
def find_event(timestamp: float) -> SceneEvent | None
```

Return the event with the given timestamp, or `None` if not present.

#### get\_event

```python theme={"dark"}
def get_event(timestamp: float) -> SceneEvent
```

Return the event with the given timestamp.

**Raises**:

* `KeyError` - If no event with that timestamp exists.

## TimeSeriesStream Objects

```python theme={"dark"}
@dataclass
class TimeSeriesStream()
```

A self-contained CSV time-series stream.

#### url

Raw unsigned URI as stored in the scene definition.

#### signed\_url

Time-limited signed URL for downloading the CSV file.

## CompositeScene Objects

```python theme={"dark"}
@dataclass
class CompositeScene()
```

A scene composed of multiple named streams.

#### find\_stream

```python theme={"dark"}
def find_stream(
    stream_id: str, *, kind: Literal["point_cloud", "image", "time_series"]
) -> PointCloudStream | ImageStream | TimeSeriesStream | None
```

Return the stream with the given ID and kind, or `None` if not present.

#### get\_stream

```python theme={"dark"}
def get_stream(
    stream_id: str, *, kind: Literal["point_cloud", "image", "time_series"]
) -> PointCloudStream | ImageStream | TimeSeriesStream
```

Return the stream with the given ID and kind.

**Raises**:

* `KeyError` - If no stream with that ID and kind exists.

#### get\_images\_at\_timestamp

```python theme={"dark"}
def get_images_at_timestamp(timestamp: float) -> list[tuple[str, SceneEvent]]
```

Return camera image events at the given timestamp across image streams.

Streams without a matching event are skipped.

## SceneReader Objects

```python theme={"dark"}
class SceneReader()
```

Read scene structure and signed URLs from a scene storage item.

#### read

```python theme={"dark"}
def read() -> Scene
```

Fetch the scene structure with signed download URLs for all constituent files.

#### to\_upload\_payload

```python theme={"dark"}
def to_upload_payload(
    title: str | None = None,
    *,
    client_metadata: dict[str, Any] | None = None,
    uri_mapper: Callable[[str], str] | Mapping[str, str] | None = None
) -> orm_storage.DataUploadScene
```

Fetch this scene and convert it to a `DataUploadScene` for re-upload.

**Arguments**:

* `title` - Title to use for the uploaded scene. Defaults to the source storage item name.
* `client_metadata` - Metadata for the uploaded scene. Defaults to the source item metadata.
* `uri_mapper` - Optional callable or mapping used to rewrite each stored URI before upload.

**Returns**:

A scene upload payload suitable for `DataUploadItems(scenes=[...])`.

## SceneRead Objects

```python theme={"dark"}
@deprecated(version="0.1.198", alternative="SceneReader")
class SceneRead(SceneReader)
```

Deprecated alias for [SceneReader](/sdk-documentation/sdk-references/beta.scene.reader#scenereader-objects).


# Beta.scene.rotation
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.rotation



Public rotation types and convenience constructors.

## QuaternionRotation Objects

```python theme={"dark"}
@dataclass
class QuaternionRotation()
```

Unit-quaternion rotation.

Each component must be in `[-1.0, 1.0]` and the quaternion must
have unit magnitude (`sqrt(qx**2 + qy**2 + qz**2 + qw**2) ≈ 1.0`,
tolerance `1e-2`). These constraints are enforced server-side.

## EulerRotation Objects

```python theme={"dark"}
@dataclass
class EulerRotation()
```

Euler-angle rotation (radians), applied as extrinsic X-Y-Z.

Each angle must be in `[-2.1pi, 2.1pi]` (roughly +/-378 degrees).
This constraint is enforced server-side.

## MatrixRotation Objects

```python theme={"dark"}
@dataclass
class MatrixRotation()
```

3x3 rotation matrix (9 floats, **column-major**).

The 9 values are stored column-by-column::

Given the matrix:
\| r00  r01  r02 |
\| r10  r11  r12 |
\| r20  r21  r22 |

Flat order: \[r00, r10, r20, r01, r11, r21, r02, r12, r22]
\-- col 0 --  -- col 1 --  -- col 2 --

The matrix must be a proper rotation matrix: each column must be a
unit vector, all column pairs must be orthogonal, and the determinant
must equal `1.0`. These constraints are enforced server-side.

#### identity\_rotation

```python theme={"dark"}
def identity_rotation() -> QuaternionRotation
```

Return the identity rotation (no rotation).

#### rotation\_x

```python theme={"dark"}
def rotation_x(angle: float) -> EulerRotation
```

Rotation around the *x*-axis only.

**Arguments**:

* `angle` - Rotation angle in radians.

#### rotation\_y

```python theme={"dark"}
def rotation_y(angle: float) -> EulerRotation
```

Rotation around the *y*-axis only.

**Arguments**:

* `angle` - Rotation angle in radians.

#### rotation\_z

```python theme={"dark"}
def rotation_z(angle: float) -> EulerRotation
```

Rotation around the *z*-axis only.

**Arguments**:

* `angle` - Rotation angle in radians.


# Beta.scene.scene to upload playload
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.scene_to_upload_playload



Public SDK scene read types.

These are stable SDK types that insulate users from the internal wire format.
They are constructed from the internal types in `beta/scene/internal/scene.py`.

#### scene\_to\_upload\_payload

```python theme={"dark"}
def scene_to_upload_payload(
    internal: _Scene,
    *,
    uri_mapper: Callable[[str], str] | Mapping[str, str] | None = None
) -> dict[str, Any]
```

Convert an internal signed scene response into scene upload JSON.


# Beta.scene.stream
Source: https://docs.encord.com/sdk-documentation/sdk-references/beta.scene.stream



Stream builder classes for constructing scene streams.

Each stream type has a dedicated builder returned by the corresponding
`add_*_stream` method on [SceneBuilder](/sdk-documentation/sdk-references/beta.scene.builder#scenebuilder-objects).

## \_StreamBuilderBase Objects

```python theme={"dark"}
class _StreamBuilderBase()
```

Internal base -- not part of the public API.

#### name

```python theme={"dark"}
@property
def name() -> str
```

The stream name used to register this stream in the [SceneBuilder](/sdk-documentation/sdk-references/beta.scene.builder#scenebuilder-objects).

## TimeSeriesStreamBuilder Objects

```python theme={"dark"}
class TimeSeriesStreamBuilder(_StreamBuilderBase)
```

Builder for a self-contained CSV time-series stream.

Returned by [add\_time\_series\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_time_series_stream).

## PCDStreamBuilder Objects

```python theme={"dark"}
class PCDStreamBuilder(_StreamBuilderBase)
```

Builder for a point-cloud stream.

Returned by [add\_pcd\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_pcd_stream).

#### add\_pcd

```python theme={"dark"}
def add_pcd(*, uri: str, timestamp: float) -> PCDStreamBuilder
```

Append a single point-cloud event.

**Arguments**:

* `uri` - Non-empty URI pointing to the point-cloud file.
* `timestamp` - Scene timestamp for this event.

#### set\_frame\_of\_reference

```python theme={"dark"}
def set_frame_of_reference(for_id: str | FoRStreamBuilder) -> PCDStreamBuilder
```

Link this stream to a frame-of-reference stream.

**Arguments**:

* `for_id` - The **stream name** of a FoR stream, or a
  [FoRStreamBuilder](/sdk-documentation/sdk-references/beta.scene.stream#forstreambuilder-objects) instance.

#### set\_pose

```python theme={"dark"}
def set_pose(pose: Pose) -> PCDStreamBuilder
```

Set a static pose for this stream.

## CameraStreamBuilder Objects

```python theme={"dark"}
class CameraStreamBuilder(_StreamBuilderBase)
```

Builder for a camera-parameters stream.

Returned by [add\_camera\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_camera_stream).

#### add\_camera\_params

```python theme={"dark"}
def add_camera_params(width: int, height: int, intrinsics: Intrinsics, *,
                      timestamp: float) -> CameraStreamBuilder
```

Append a camera-parameters event.

**Arguments**:

* `width` - Image width in pixels (must be >= 0).
* `height` - Image height in pixels (must be >= 0).
* `intrinsics` - Camera intrinsics ([SimpleIntrinsics](/sdk-documentation/sdk-references/beta.scene.intrinsics#simpleintrinsics-objects) or
  [AdvancedIntrinsics](/sdk-documentation/sdk-references/beta.scene.intrinsics#advancedintrinsics-objects)).
* `timestamp` - Scene timestamp for this event.

#### set\_frame\_of\_reference

```python theme={"dark"}
def set_frame_of_reference(
        for_id: str | FoRStreamBuilder) -> CameraStreamBuilder
```

Link this stream to a frame-of-reference stream.

**Arguments**:

* `for_id` - The **stream name** of a FoR stream, or a
  [FoRStreamBuilder](/sdk-documentation/sdk-references/beta.scene.stream#forstreambuilder-objects) instance.

#### set\_pose

```python theme={"dark"}
def set_pose(pose: Pose) -> CameraStreamBuilder
```

Set a static pose for this stream.

## FoRStreamBuilder Objects

```python theme={"dark"}
class FoRStreamBuilder(_StreamBuilderBase)
```

Builder for a frame-of-reference (FoR) stream.

Returned by [add\_for\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_for_stream).

#### add\_pose

```python theme={"dark"}
def add_pose(pose: Pose, *, timestamp: float) -> FoRStreamBuilder
```

Append a frame-of-reference event.

**Arguments**:

* `pose` - The pose for this event (any supported rotation
  encoding).
* `timestamp` - Scene timestamp for this event.

## ImageStreamBuilder Objects

```python theme={"dark"}
class ImageStreamBuilder(_StreamBuilderBase)
```

Builder for an image stream linked to a camera.

Returned by [add\_image\_stream()](/sdk-documentation/sdk-references/beta.scene.builder#add_image_stream).

#### add\_image

```python theme={"dark"}
def add_image(*, uri: str, timestamp: float) -> ImageStreamBuilder
```

Append an image event.

**Arguments**:

* `uri` - Non-empty URI pointing to the image file.
* `timestamp` - Scene timestamp for this event.


# Client
Source: https://docs.encord.com/sdk-documentation/sdk-references/client



`encord.client` provides a simple Python client that allows you
to query project resources through the Encord API.

Here is a simple example for instantiating the client for a project
and obtaining project info:

.. test\_blurb2.py code::

from encord.client import EncordClient

client = EncordClient.initialize('YourProjectID', 'YourAPIKey')
client.get\_project()

**Returns**:

* `Project` - A project record instance. See Project ORM for details.

## EncordClient Objects

```python theme={"dark"}
class EncordClient()
```

Encord client. Allows you to query db items associated
with a project (e.g. label rows, datasets).

## EncordClientDataset Objects

```python theme={"dark"}
class EncordClientDataset(EncordClient)
```

DEPRECATED - prefer using the [Dataset](/sdk-documentation/sdk-references/dataset#dataset-objects) instead

#### get\_dataset

```python theme={"dark"}
def get_dataset(*, fetch_rows: bool = True) -> OrmDataset
```

Retrieve dataset info (pointers to data, labels).

**Arguments**:

* `fetch_rows` - Whether to fetch the dataset's data rows. Defaults to `True`. Pass
  `False` to retrieve dataset metadata only (no data rows), which is much
  cheaper for large datasets.

**Returns**:

* `OrmDataset` - A dataset record instance.

**Raises**:

* `AuthorisationError` - If the dataset API key is invalid.
* `ResourceNotFoundError` - If no dataset exists by the specified dataset EntityId.
* `UnknownError` - If an error occurs while retrieving the dataset.

#### list\_data\_rows

```python theme={"dark"}
def list_data_rows(title_eq: Optional[str] = None,
                   title_like: Optional[str] = None,
                   created_before: Optional[Union[str, datetime]] = None,
                   created_after: Optional[Union[str, datetime]] = None,
                   data_types: Optional[List[DataType]] = None,
                   data_hashes: Optional[List[str]] = None) -> List[DataRow]
```

Retrieve dataset rows (pointers to data, labels).

**Arguments**:

* `title_eq` - optional exact title row filter
* `title_like` - optional fuzzy title row filter; SQL syntax
* `created_before` - optional datetime row filter
* `created_after` - optional datetime row filter
* `data_types` - optional data types row filter
* `data_hashes` - optional list of individual data unit hashes to include

**Returns**:

* `List[DataRow]` - A list of DataRows object that match the filter

**Raises**:

* `AuthorisationError` - If the dataset API key is invalid.
* `ResourceNotFoundError` - If no dataset exists by the specified dataset EntityId.
* `UnknownError` - If an error occurs while retrieving the dataset.

#### add\_users

```python theme={"dark"}
def add_users(user_emails: List[str],
              user_role: DatasetUserRole) -> List[DatasetUser]
```

This function is documented in [add\_users()](/sdk-documentation/sdk-references/project#add_users).

#### upload\_video

```python theme={"dark"}
def upload_video(
        file_path: Union[str, Path],
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        title: Optional[str] = None,
        folder_uuid: Optional[uuid.UUID] = None) -> Video
```

This function is documented in [upload\_video()](/sdk-documentation/sdk-references/dataset#upload_video).

#### create\_image\_group

```python theme={"dark"}
def create_image_group(
        file_paths: Iterable[Union[str, Path]],
        max_workers: Optional[int] = None,
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        title: Optional[str] = None,
        *,
        create_video: bool = True,
        folder_uuid: Optional[uuid.UUID] = None) -> List[ImageGroup]
```

This function is documented in [create\_image\_group()](/sdk-documentation/sdk-references/dataset#create_image_group).

#### create\_dicom\_series

```python theme={"dark"}
def create_dicom_series(
        file_paths: Union[typing.Collection[str], typing.Collection[Path],
                          typing.Collection[Union[str, Path]]],
        title: Optional[str] = None,
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        folder_uuid: Optional[uuid.UUID] = None) -> Dict
```

This function is documented in [create\_dicom\_series()](/sdk-documentation/sdk-references/dataset#create_dicom_series).

#### upload\_image

```python theme={"dark"}
def upload_image(
        file_path: Union[Path, str],
        title: Optional[str] = None,
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        folder_uuid: Optional[uuid.UUID] = None) -> Image
```

This function is documented in [upload\_image()](/sdk-documentation/sdk-references/dataset#upload_image).

#### link\_items

```python theme={"dark"}
def link_items(
    item_uuids: List[uuid.UUID],
    duplicates_behavior: DataLinkDuplicatesBehavior = DataLinkDuplicatesBehavior
    .SKIP
) -> List[DataRow]
```

Link storage items to the dataset, creating new data rows.

**Arguments**:

* `item_uuids` - List of item UUIDs to link to the dataset
* `duplicates_behavior` - The behavior to follow when encountering duplicates. Defaults to `SKIP`. See also
  [DataLinkDuplicatesBehavior](/sdk-documentation/sdk-references/orm.dataset#datalinkduplicatesbehavior-objects)

#### delete\_data

```python theme={"dark"}
def delete_data(data_hashes: Union[List[str], str])
```

This function is documented in [delete\_data()](/sdk-documentation/sdk-references/dataset#delete_data).

#### add\_private\_data\_to\_dataset

```python theme={"dark"}
def add_private_data_to_dataset(
        integration_id: str,
        private_files: Union[str, typing.Dict, Path, typing.TextIO],
        ignore_errors: bool = False) -> AddPrivateDataResponse
```

This function is documented in [add\_private\_data\_to\_dataset()](/sdk-documentation/sdk-references/dataset#add_private_data_to_dataset).

#### add\_private\_data\_to\_dataset\_start

```python theme={"dark"}
def add_private_data_to_dataset_start(
        integration_id: str,
        private_files: Union[str, typing.Dict, Path, typing.TextIO],
        ignore_errors: bool = False,
        folder_uuid: Optional[uuid.UUID] = None) -> str
```

This function is documented in [add\_private\_data\_to\_dataset\_start()](/sdk-documentation/sdk-references/dataset#add_private_data_to_dataset_start).

#### add\_private\_data\_to\_dataset\_get\_result

```python theme={"dark"}
def add_private_data_to_dataset_get_result(
        upload_job_id: str,
        timeout_seconds: int = 7 * 24 * 60 * 60) -> DatasetDataLongPolling
```

This function is documented in [add\_private\_data\_to\_dataset\_get\_result()](/sdk-documentation/sdk-references/dataset#add_private_data_to_dataset_get_result).

#### update\_data\_item

```python theme={"dark"}
def update_data_item(data_hash: str, new_title: str) -> bool
```

This function is documented in [update\_data\_item()](/sdk-documentation/sdk-references/dataset#update_data_item).

#### re\_encode\_data

```python theme={"dark"}
def re_encode_data(data_hashes: List[str])
```

This function is documented in [re\_encode\_data()](/sdk-documentation/sdk-references/dataset#re_encode_data).

#### re\_encode\_data\_status

```python theme={"dark"}
def re_encode_data_status(job_id: int)
```

This function is documented in [re\_encode\_data\_status()](/sdk-documentation/sdk-references/dataset#re_encode_data_status).

## EncordClientProject Objects

```python theme={"dark"}
class EncordClientProject(EncordClient)
```

DEPRECATED - prefer using the [Project](/sdk-documentation/sdk-references/project#project-objects) instead

#### get\_project

```python theme={"dark"}
def get_project(include_labels_metadata=True) -> OrmProject
```

Retrieve project info (pointers to data, labels).

**Arguments**:

* `include_labels_metadata` - if false, label row metadata information will not be returned.

**Returns**:

* `OrmProject` - A project record instance.

**Raises**:

* `AuthorisationError` - If the project API key is invalid.
* `ResourceNotFoundError` - If no project exists by the specified project EntityId.
* `UnknownError` - If an error occurs while retrieving the project.

#### get\_project\_v2

```python theme={"dark"}
def get_project_v2() -> ProjectOrmV2
```

This is an internal method, do not use it directly.
Use [get\_project()](/sdk-documentation/sdk-references/client#get_project) instead.

#### list\_label\_rows

```python theme={"dark"}
def list_label_rows(
        edited_before: Optional[Union[str, datetime]] = None,
        edited_after: Optional[Union[str, datetime]] = None,
        label_statuses: Optional[List[AnnotationTaskStatus]] = None,
        shadow_data_state: Optional[ShadowDataState] = None,
        *,
        include_uninitialised_labels: bool = False,
        include_workflow_graph_node: bool = True,
        include_client_metadata: bool = False,
        include_images_data: bool = False,
        include_children: bool = False,
        label_hashes: Optional[Union[List[str], List[UUID]]] = None,
        data_hashes: Optional[Union[List[str], List[UUID]]] = None,
        data_title_eq: Optional[str] = None,
        data_title_like: Optional[str] = None,
        workflow_graph_node_title_eq: Optional[str] = None,
        workflow_graph_node_title_like: Optional[str] = None,
        include_all_label_branches: bool = False,
        branch_name: Optional[str] = None,
        client_metadata_as_signed_url: bool = False) -> List[LabelRowMetadata]
```

This function is documented in [list\_label\_rows()](/sdk-documentation/sdk-references/project#list_label_rows).

#### add\_users

```python theme={"dark"}
def add_users(user_emails: List[str],
              user_role: ProjectUserRole) -> List[ProjectUser]
```

This function is documented in [add\_users()](/sdk-documentation/sdk-references/project#add_users).

#### copy\_project

```python theme={"dark"}
def copy_project(copy_datasets: Union[bool, CopyDatasetOptions] = False,
                 copy_collaborators=False,
                 copy_models=False,
                 *,
                 copy_labels: Optional[CopyLabelsOptions] = None,
                 new_title: Optional[str] = None,
                 new_description: Optional[str] = None) -> str
```

This function is documented in [copy\_project()](/sdk-documentation/sdk-references/project#copy_project).

#### get\_label\_row

```python theme={"dark"}
def get_label_row(uid: str,
                  get_signed_url: bool = True,
                  *,
                  include_object_feature_hashes: Optional[
                      typing.Set[str]] = None,
                  include_classification_feature_hashes: Optional[
                      typing.Set[str]] = None,
                  include_reviews: bool = False,
                  include_export_history: bool = False) -> LabelRow
```

This function is documented in [get\_label\_row()](/sdk-documentation/sdk-references/project#get_label_row).

#### get\_label\_rows

```python theme={"dark"}
def get_label_rows(uids: List[str],
                   get_signed_url: bool = True,
                   *,
                   include_object_feature_hashes: Optional[
                       typing.Set[str]] = None,
                   include_classification_feature_hashes: Optional[
                       typing.Set[str]] = None,
                   include_reviews: bool = False,
                   include_export_history: bool = False,
                   include_archived: bool = False) -> List[LabelRow]
```

This function is documented in [get\_label\_rows()](/sdk-documentation/sdk-references/project#get_label_rows).

#### save\_label\_row

```python theme={"dark"}
def save_label_row(uid, label, validate_before_saving: bool = False)
```

This function is documented in [save\_label\_row()](/sdk-documentation/sdk-references/project#save_label_row).

#### save\_label\_rows

```python theme={"dark"}
def save_label_rows(uids: List[str],
                    payload: List[LabelRow],
                    validate_before_saving: bool = False)
```

This function is meant for internal use, please consider using [LabelRowV2](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects) class instead

Saves multiple label rows. See [save\_label\_row()](/sdk-documentation/sdk-references/client#save_label_row)

**Arguments**:

* `uids` - list of label hashes
* `payload` - list of LabelRow objects
* `validate_before_saving` - ????

**Returns**:

None

#### create\_label\_row

```python theme={"dark"}
def create_label_row(uid, *, get_signed_url=False) -> LabelRow
```

This function is documented in [create\_label\_row()](/sdk-documentation/sdk-references/project#create_label_row).

#### create\_label\_rows

```python theme={"dark"}
def create_label_rows(uids: List[str],
                      *,
                      get_signed_url: bool = False,
                      branch_name: Optional[str] = None) -> List[LabelRow]
```

This function is meant for internal use, please consider using [LabelRowV2](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects) class instead

Create multiple label rows. See [create\_label\_row()](/sdk-documentation/sdk-references/client#create_label_row)

**Arguments**:

* `uids` - list of data uids where label\_status is NOT\_LABELLED.
* `get_signed_url` - bool whether to fetch the signed url for the internal label row
* `branch_name` - Optional\[str] which branch name against which to create the label row

**Returns**:

* `List[LabelRow]` - A list of created label rows

#### add\_datasets

```python theme={"dark"}
def add_datasets(dataset_hashes: List[str]) -> bool
```

This function is documented in [add\_datasets()](/sdk-documentation/sdk-references/project#add_datasets).

#### remove\_datasets

```python theme={"dark"}
def remove_datasets(dataset_hashes: List[str]) -> bool
```

This function is documented in [remove\_datasets()](/sdk-documentation/sdk-references/project#remove_datasets).

#### add\_object

```python theme={"dark"}
@deprecated("0.1.102", alternative="encord.ontology.Ontology class")
def add_object(name: str, shape: ObjectShape) -> bool
```

This function is documented in [add\_object()](/sdk-documentation/sdk-references/project#add_object).

#### add\_classification

```python theme={"dark"}
@deprecated("0.1.102", alternative="encord.ontology.Ontology class")
def add_classification(name: str,
                       classification_type: ClassificationType,
                       required: bool,
                       options: Optional[Iterable[str]] = None)
```

This function is documented in [add\_classification()](/sdk-documentation/sdk-references/project#add_classification).

#### object\_interpolation

```python theme={"dark"}
def object_interpolation(key_frames, objects_to_interpolate)
```

This function is documented in [object\_interpolation()](/sdk-documentation/sdk-references/project#object_interpolation).

#### get\_data

```python theme={"dark"}
def get_data(
    data_hash: str,
    get_signed_url: bool = False
) -> Tuple[Optional[Video], Optional[List[Image]]]
```

This function is documented in [get\_data()](/sdk-documentation/sdk-references/project#get_data).

#### get\_label\_logs

```python theme={"dark"}
def get_label_logs(user_hash: Optional[str] = None,
                   data_hash: Optional[str] = None,
                   from_unix_seconds: Optional[int] = None,
                   to_unix_seconds: Optional[int] = None,
                   after: Optional[datetime] = None,
                   before: Optional[datetime] = None,
                   user_email: Optional[str] = None) -> List[LabelLog]
```

This function is documented in [get\_label\_logs()](/sdk-documentation/sdk-references/project#get_label_logs).

#### workflow\_reopen

```python theme={"dark"}
def workflow_reopen(label_hashes: List[str]) -> None
```

This function is documented in [workflow\_reopen()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#workflow_reopen).

#### workflow\_complete

```python theme={"dark"}
def workflow_complete(label_hashes: List[str]) -> None
```

This function is documented in [workflow\_complete()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#workflow_complete).


# Client metadata schema
Source: https://docs.encord.com/sdk-documentation/sdk-references/client_metadata_schema



#### set\_client\_metadata\_schema\_from\_dict

```python theme={"dark"}
@deprecated("0.1.132")
def set_client_metadata_schema_from_dict(
        api_client: ApiClient, json_dict: Dict[str,
                                               orm.ClientMetadataSchemaTypes])
```

Set the client metadata schema from a dictionary.

**Arguments**:

* `api_client` *ApiClient* - The API client to use for the request.
* `json_dict` *Dict\[str, orm.ClientMetadataSchemaTypes]* - A dictionary containing the client metadata schema types.

**Raises**:

* `NotImplementedError` - If an unexpected data type is encountered in the schema.

#### get\_client\_metadata\_schema

```python theme={"dark"}
@deprecated("0.1.132")
def get_client_metadata_schema(
    api_client: ApiClient
) -> Optional[Dict[str, orm.ClientMetadataSchemaTypes]]
```

Retrieve the client metadata schema.

**Arguments**:

* `api_client` *ApiClient* - The API client to use for the request.

**Returns**:

Optional\[Dict\[str, orm.ClientMetadataSchemaTypes]]: A dictionary containing the client metadata schema types
if available, otherwise None.


# Collection
Source: https://docs.encord.com/sdk-documentation/sdk-references/collection



## Collection Objects

```python theme={"dark"}
class Collection()
```

Represents collections in Index.
Collections are a logical grouping of data items that can be used to
create datasets and perform various data curation flows.

#### uuid

```python theme={"dark"}
@property
def uuid() -> UUID
```

Get the collection unique identifier (UUID).

**Returns**:

* `UUID` - The collection UUID.

#### name

```python theme={"dark"}
@property
def name() -> str
```

Get the collection name.

**Returns**:

* `str` - The collection name.

#### description

```python theme={"dark"}
@property
def description() -> Optional[str]
```

Get the collection description.

**Returns**:

* `Optional[str]` - The collection description, or None if not available.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> Optional[datetime]
```

Get the collection creation timestamp.

**Returns**:

* `Optional[datetime]` - The timestamp when the collection was created, or None if not available.

#### last\_edited\_at

```python theme={"dark"}
@property
def last_edited_at() -> Optional[datetime]
```

Get the collection last edit timestamp.

**Returns**:

* `Optional[datetime]` - The timestamp when the collection was last edited, or None if not available.

#### top\_level\_folder\_uuid

```python theme={"dark"}
@property
def top_level_folder_uuid() -> UUID
```

Get the uuid of the top level folder that the collection is on.

**Returns**:

* `UUID` - the uuid of the top level folder that the collection is on

#### update\_collection

```python theme={"dark"}
def update_collection(name: Optional[str] = None,
                      description: Optional[str] = None) -> None
```

Update the collection's name and/or description.

**Arguments**:

* `name` *Optional\[str]* - The new name for the collection.
* `description` *Optional\[str]* - The new description for the collection.

#### list\_items

```python theme={"dark"}
def list_items(include_client_metadata: Optional[bool] = None,
               page_size: Optional[int] = None) -> Iterator[StorageItem]
```

List storage items in the collection.

**Arguments**:

* `include_client_metadata` *Optional\[bool]* - Whether to include client metadata for each item.
* `page_size` *Optional\[int]* - The number of items to fetch per page.

**Returns**:

* `Iterator[StorageItem]` - An iterator containing storage items in the collection.

#### list\_items\_include\_inaccessible

```python theme={"dark"}
def list_items_include_inaccessible(
    include_client_metadata: Optional[bool] = None,
    page_size: Optional[int] = None
) -> Iterator[Union[StorageItem, StorageItemInaccessible]]
```

List storage items in the collection, including those that are inaccessible.

**Arguments**:

* `include_client_metadata` *Optional\[bool]* - Whether to include client metadata for each item.
* `page_size` *Optional\[int]* - The number of items to fetch per page.

**Returns**:

Iterator\[Union\[StorageItem, StorageItemInaccessible]]: An iterator containing both accessible
and inaccessible storage items in the collection.

#### add\_items

```python theme={"dark"}
def add_items(
    storage_item_uuids: Sequence[Union[UUID,
                                       str]]) -> CollectionBulkItemResponse
```

Add storage items to the collection.

**Arguments**:

* `storage_item_uuids` *Sequence\[Union\[UUID, str]]* - The list of storage item UUIDs to be added.
  Either UUIDs or string representations of UUIDs are accepted.

**Returns**:

* `CollectionBulkItemResponse` - The response after adding items to the collection.

#### remove\_items

```python theme={"dark"}
def remove_items(
    storage_item_uuids: Sequence[Union[UUID,
                                       str]]) -> CollectionBulkItemResponse
```

Remove storage items from the collection.

**Arguments**:

* `storage_item_uuids` *Sequence\[Union\[UUID, str]]* - The list of storage item UUIDs to be removed.
  Either UUIDs or string representations of UUIDs are accepted.

**Returns**:

* `CollectionBulkItemResponse` - The response after removing items from the collection.

#### add\_preset\_items

```python theme={"dark"}
def add_preset_items(filter_preset: Union[FilterPreset, UUID, str]) -> None
```

Async operation to add storage items matching a filter preset to the collection.

**Arguments**:

* `filter_preset` *Union\[FilterPreset, UUID, str]* - The filter preset or its UUID/ID used to filter items.

#### remove\_preset\_items

```python theme={"dark"}
def remove_preset_items(filter_preset: Union[FilterPreset, UUID, str]) -> None
```

Async operation to remove storage items matching a filter preset from the collection.

**Arguments**:

* `filter_preset` *Union\[FilterPreset, UUID, str]* - The filter preset or its UUID/ID used to filter items.

## ProjectCollection Objects

```python theme={"dark"}
class ProjectCollection()
```

Represents Active collections inside a Project.
Active Project Collections are a logical grouping of frames (images or video frames) or
annotations (objects and classifications) that can be used to perform various data curation flows.

#### uuid

```python theme={"dark"}
@property
def uuid() -> UUID
```

Get the collection unique identifier (UUID).

**Returns**:

* `UUID` - The collection UUID.

#### name

```python theme={"dark"}
@property
def name() -> str
```

Get the collection name.

**Returns**:

* `str` - The collection name.

#### description

```python theme={"dark"}
@property
def description() -> Optional[str]
```

Get the collection description.

**Returns**:

* `Optional[str]` - The collection description, or None if not available.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> Optional[datetime]
```

Get the collection creation timestamp.

**Returns**:

* `Optional[datetime]` - The timestamp when the collection was created, or None if not available.

#### last\_edited\_at

```python theme={"dark"}
@property
def last_edited_at() -> Optional[datetime]
```

Get the collection last edit timestamp.

**Returns**:

* `Optional[datetime]` - The timestamp when the collection was last edited, or None if not available.

#### collection\_type

```python theme={"dark"}
@property
def collection_type() -> ProjectCollectionType
```

Get the type of the collection.

**Returns**:

* `ProjectCollectionType` - The type of the collection.

#### project\_hash

```python theme={"dark"}
@property
def project_hash() -> UUID
```

Get the project hash of the collection.

**Returns**:

* `UUID` - The project hash of the collection.

#### update\_collection

```python theme={"dark"}
def update_collection(name: Optional[str] = None,
                      description: Optional[str] = None) -> None
```

Update the collection's name and/or description.

**Arguments**:

* `name` *Optional\[str]* - The new name for the collection.
* `description` *Optional\[str]* - The new description for the collection.

#### list\_frames

```python theme={"dark"}
def list_frames(
    page_size: Optional[int] = None
) -> Iterator[Tuple[LabelRowV2, List[ProjectDataCollectionInstance]]]
```

List frames in the collection.

**Arguments**:

* `page_size` *Optional\[int]* - The number of items to fetch per page.

**Returns**:

Iterator\[Tuple\[LabelRowV2, List\[ProjectDataCollectionInstance]]]: An list of tuples containing label
row and corresponding frame instances in the collection.

#### list\_annotations

```python theme={"dark"}
def list_annotations(
    page_size: Optional[int] = None
) -> Iterator[Tuple[LabelRowV2, List[ProjectLabelCollectionInstance]]]
```

List annotations in the collection.

**Arguments**:

* `page_size` *Optional\[int]* - The number of items to fetch per page.

**Returns**:

Iterator\[Tuple\[LabelRowV2, List\[ProjectLabelCollectionInstance]]]: An list of tuples containing label
row and corresponding label instances in the collection.

#### add\_items

```python theme={"dark"}
def add_items(
    items: List[Union[ProjectDataCollectionItemRequest,
                      ProjectLabelCollectionItemRequest]]
) -> ProjectCollectionBulkItemResponse
```

Add data items to the collection.

**Arguments**:

* `items` *Sequence\[ProjectDataCollectionItemRequest | ProjectLabelCollectionItemRequest]* - The list of data items to be added.

**Returns**:

* `ProjectCollectionBulkItemResponse` - The response after adding items to the collection.

#### remove\_items

```python theme={"dark"}
def remove_items(
    items: List[Union[ProjectDataCollectionItemRequest,
                      ProjectLabelCollectionItemRequest]]
) -> ProjectCollectionBulkItemResponse
```

Remove data items from the collection.

**Arguments**:

* `items` *Sequence\[ProjectDataCollectionItemRequest | ProjectLabelCollectionItemRequest]* - The list of data items to be removed.

**Returns**:

* `ProjectCollectionBulkItemResponse` - The response after removing items from the collection.

#### add\_preset\_items

```python theme={"dark"}
def add_preset_items(filter_preset: Union[FilterPreset, UUID, str]) -> None
```

Async operation to add storage items matching a filter preset to the collection.

**Arguments**:

* `filter_preset` *Union\[FilterPreset, UUID, str]* - The filter preset or its UUID/ID used to filter items.

#### remove\_preset\_items

```python theme={"dark"}
def remove_preset_items(filter_preset: Union[FilterPreset, UUID, str]) -> None
```

Async operation to remove storage items matching a filter preset from the collection.

**Arguments**:

* `filter_preset` *Union\[FilterPreset, UUID, str]* - The filter preset or its UUID/ID used to filter items.


# Common.bitmask operations.bitmask operations
Source: https://docs.encord.com/sdk-documentation/sdk-references/common.bitmask_operations.bitmask_operations



#### encord\_rle\_to\_coco\_rle

```python theme={"dark"}
def encord_rle_to_coco_rle(encord_rle_string: str, *, height: int,
                           width: int) -> str
```

Convert an Encord-compatible RLE string to a COCO-compatible RLE counts string.

Encord bitmasks are encoded from row-major mask data. COCO RLE counts are encoded
from column-major mask data, as produced by pycocotools.

#### coco\_rle\_to\_encord\_rle

```python theme={"dark"}
def coco_rle_to_encord_rle(coco_rle_string: str, *, height: int,
                           width: int) -> str
```

Convert a COCO-compatible RLE counts string to an Encord-compatible RLE string.

COCO RLE counts are encoded from column-major mask data, as produced by
pycocotools. Encord bitmasks are encoded from row-major mask data.

#### ranges\_to\_rle\_counts

```python theme={"dark"}
def ranges_to_rle_counts(ranges: Sequence[Tuple[int, int]]) -> List[int]
```

Convert sorted non-overlapping ranges to RLE counts.

This is O(number of ranges) rather than O(number of points), making it
efficient for large point sets represented as ranges.

**Arguments**:

* `ranges` - Sorted list of (start, end) tuples representing inclusive ranges.
  Ranges must be non-overlapping and sorted by start.

**Returns**:

List of RLE counts alternating between empty and present runs


# Common.enum
Source: https://docs.encord.com/sdk-documentation/sdk-references/common.enum



## StringEnum Objects

```python theme={"dark"}
class StringEnum(str, Enum)
```

Use this enum class if you need the helper that creates the enum instance from a string.


# Common.integer range set
Source: https://docs.encord.com/sdk-documentation/sdk-references/common.integer_range_set



## IntegerRangeSet Objects

```python theme={"dark"}
class IntegerRangeSet()
```

#### intersection

```python theme={"dark"}
def intersection(start: int, end: int) -> Optional[List[Tuple[int, int]]]
```

Returns a list of overlapping tuples or None.
Complexity: O(log N + K) where K is the number of overlapping fragments.

#### remove

```python theme={"dark"}
def remove(start: int, end: int) -> None
```

Removes a range, splitting or deleting existing ranges.


# Common.range manager
Source: https://docs.encord.com/sdk-documentation/sdk-references/common.range_manager



## RangeManager Objects

```python theme={"dark"}
class RangeManager()
```

Range Manager implemented using IntegerRangeSet for optimal performance.

This is a wrapper around IntegerRangeSet that provides the same API as RangeManager
but with improved performance characteristics.

#### add\_range

```python theme={"dark"}
def add_range(new_range: Range) -> None
```

Add a range, merging any overlapping ranges.

#### add\_ranges

```python theme={"dark"}
def add_ranges(new_ranges: Ranges) -> None
```

Add multiple ranges.

#### remove\_range

```python theme={"dark"}
def remove_range(range_to_remove: Range) -> None
```

Remove a specific range using IntegerRangeSet's native remove method.

#### remove\_ranges

```python theme={"dark"}
def remove_ranges(ranges_to_remove: Ranges) -> None
```

Remove multiple ranges.

#### clear\_ranges

```python theme={"dark"}
def clear_ranges() -> None
```

Clear all ranges.

#### get\_ranges

```python theme={"dark"}
def get_ranges() -> Ranges
```

Return the sorted list of merged ranges.

#### get\_ranges\_as\_frames

```python theme={"dark"}
def get_ranges_as_frames() -> Set[int]
```

Returns set of intersecting frames.

#### intersection

```python theme={"dark"}
def intersection(other_frame_class: Frames) -> Ranges
```

Returns list of intersecting ranges.


# Common.time parser
Source: https://docs.encord.com/sdk-documentation/sdk-references/common.time_parser



#### parse\_datetime

```python theme={"dark"}
@lru_cache(maxsize=8192)
def parse_datetime(time_string: str) -> datetime
```

Parsing datetime strings to timezone-aware datetime objects efficiently.

If no timezone information is present in the string, UTC is assumed.

Our labels can contain timestamps in different formats, but applying dateutil.parse straight away is expensive
as it is very smart and tries to guess the time format.

So instead we're applying parsers with known formats, starting from the formats most likely to occur,
and falling back to the most complicated logic only in case of all other attempts have failed.

**Arguments**:

* `time_string` - A string containing a datetime in various possible formats.

**Returns**:

A timezone-aware datetime object (UTC if no timezone was specified).

#### format\_datetime\_to\_long\_string

```python theme={"dark"}
def format_datetime_to_long_string(_datetime: datetime) -> str
```

Format a datetime object to a string in the DATETIME\_LONG\_STRING\_FORMAT format.


# Common.utils
Source: https://docs.encord.com/sdk-documentation/sdk-references/common.utils



#### validate\_user\_agent\_suffix

```python theme={"dark"}
def validate_user_agent_suffix(user_agent_suffix: str) -> str
```

Validate a User-Agent string according to RFC 9110, excluding comments.
Returns it whitespace trimmed

**Arguments**:

* `user_agent_suffix` - The User-Agent string to validate

**Returns**:

The validated User-Agent string

**Raises**:

* `ValueError` - If the User-Agent string is invalid


# Configs
Source: https://docs.encord.com/sdk-documentation/sdk-references/configs



## BaseConfig Objects

```python theme={"dark"}
class BaseConfig(ABC)
```

Abstract base class for configuration.

**Arguments**:

* `endpoint` *str* - The API endpoint URL.
* `requests_settings` *RequestsSettings* - Settings for HTTP requests.

**Attributes**:

* `read_timeout` *int* - Timeout for read operations.
* `write_timeout` *int* - Timeout for write operations.
* `connect_timeout` *int* - Timeout for connection operations.
* `endpoint` *str* - The API endpoint URL.
* `requests_settings` *RequestsSettings* - Settings for HTTP requests.

#### define\_headers

```python theme={"dark"}
@abstractmethod
def define_headers(resource_id: Optional[str], resource_type: Optional[str],
                   data: str) -> Dict[str, Any]
```

Define headers for a request.

**Arguments**:

* `resource_id` *Optional\[str]* - The resource ID.
* `resource_type` *Optional\[str]* - The resource type.
* `data` *str* - The request data.

**Returns**:

Dict\[str, Any]: A dictionary of headers.

#### define\_headers\_v2

```python theme={"dark"}
@abstractmethod
def define_headers_v2(request: PreparedRequest) -> PreparedRequest
```

Define headers for a request (v2).

**Arguments**:

* `request` *PreparedRequest* - The prepared request.

**Returns**:

* `PreparedRequest` - The prepared request with headers defined.

## UserConfig Objects

```python theme={"dark"}
class UserConfig(BaseConfig)
```

Configuration for user-specific requests, redirecting to the "/public/user" endpoint.

**Arguments**:

* `config` *Config* - The base configuration.

**Attributes**:

* `config` *Config* - The base configuration.

#### domain

```python theme={"dark"}
@property
def domain() -> str
```

Get the domain from the base configuration.

**Returns**:

* `str` - The domain.

#### define\_headers

```python theme={"dark"}
def define_headers(resource_id: Optional[str], resource_type: Optional[str],
                   data: str) -> Dict[str, Any]
```

Define headers for a user-specific request.

**Arguments**:

* `resource_id` *Optional\[str]* - The resource ID.
* `resource_type` *Optional\[str]* - The resource type.
* `data` *str* - The request data.

**Returns**:

Dict\[str, Any]: A dictionary of headers.

#### define\_headers\_v2

```python theme={"dark"}
def define_headers_v2(request: PreparedRequest) -> PreparedRequest
```

Define headers for a user-specific request (v2).

**Arguments**:

* `request` *PreparedRequest* - The prepared request.

**Returns**:

* `PreparedRequest` - The prepared request with headers defined.

## Config Objects

```python theme={"dark"}
class Config(BaseConfig)
```

Configuration defining endpoint, project ID, API key, and timeouts.

**Arguments**:

* `web_file_path` *str* - The web file path for the endpoint.
* `domain` *Optional\[str]* - The domain. Trailing slashes are stripped.
* `requests_settings` *RequestsSettings* - Settings for HTTP requests.

**Attributes**:

* `domain` *str* - The domain, without any trailing slash.

#### get\_env\_ssh\_key

```python theme={"dark"}
def get_env_ssh_key() -> str
```

Get the raw SSH key from environment variables.

**Returns**:

* `str` - The raw SSH key.

**Raises**:

* `ResourceNotFoundError` - If the SSH key file or key is not found or is empty.

## SshConfig Objects

```python theme={"dark"}
class SshConfig(Config)
```

Configuration for SSH key-based authorization.

**Arguments**:

* `private_key` *Ed25519PrivateKey* - The private SSH key.
* `domain` *str* - The domain.
* `requests_settings` *RequestsSettings* - Settings for HTTP requests.

**Attributes**:

* `private_key` *Ed25519PrivateKey* - The private SSH key.
* `public_key` *Ed25519PublicKey* - The public SSH key.
* `public_key_hex` *str* - The public key in hexadecimal format.

#### define\_headers

```python theme={"dark"}
def define_headers(resource_id: Optional[str], resource_type: Optional[str],
                   data: str) -> Dict[str, Any]
```

Define headers for an SSH key-based request.

**Arguments**:

* `resource_id` *Optional\[str]* - The resource ID.
* `resource_type` *Optional\[str]* - The resource type.
* `data` *str* - The request data.

**Returns**:

Dict\[str, Any]: A dictionary of headers.

#### define\_headers\_v2

```python theme={"dark"}
def define_headers_v2(request: PreparedRequest) -> PreparedRequest
```

Define headers for an SSH key-based request (v2).

**Arguments**:

* `request` *PreparedRequest* - The prepared request.

**Returns**:

* `PreparedRequest` - The prepared request with headers defined.

#### from\_ssh\_private\_key

```python theme={"dark"}
@staticmethod
def from_ssh_private_key(
        ssh_private_key: str,
        password: Optional[str] = "",
        requests_settings: RequestsSettings = DEFAULT_REQUESTS_SETTINGS,
        domain: str = ENCORD_DOMAIN,
        **kwargs) -> SshConfig
```

Instantiate a SshConfig object by the content of a private SSH key.

**Arguments**:

* `ssh_private_key` - The content of a private key file.
* `password` - The password for the private key file.
* `requests_settings` - The requests settings for all outgoing network requests.
* `domain` - Base domain for the endpoints

**Returns**:

* `SshConfig` - The SSH configuration.

**Raises**:

* `ValueError` - If the provided key content is not of the correct format.

## BearerConfig Objects

```python theme={"dark"}
class BearerConfig(Config)
```

Configuration for bearer token-based authorization.

**Arguments**:

* `token` *str* - The bearer token.
* `domain` *str* - The domain.
* `requests_settings` *RequestsSettings* - Settings for HTTP requests.

**Attributes**:

* `token` *str* - The bearer token.

#### define\_headers

```python theme={"dark"}
def define_headers(resource_id: Optional[str], resource_type: Optional[str],
                   data: str) -> Dict[str, Any]
```

Define headers for a bearer token-based request.

**Arguments**:

* `resource_id` *Optional\[str]* - The resource ID.
* `resource_type` *Optional\[str]* - The resource type.
* `data` *str* - The request data.

**Returns**:

Dict\[str, Any]: A dictionary of headers.

#### define\_headers\_v2

```python theme={"dark"}
def define_headers_v2(request: PreparedRequest) -> PreparedRequest
```

Define headers for a bearer token-based request (v2).

**Arguments**:

* `request` *PreparedRequest* - The prepared request.

**Returns**:

* `PreparedRequest` - The prepared request with headers defined.

#### from\_bearer\_token

```python theme={"dark"}
@staticmethod
def from_bearer_token(
        token: str,
        requests_settings: RequestsSettings = DEFAULT_REQUESTS_SETTINGS,
        domain: str = ENCORD_DOMAIN,
        **kwargs) -> BearerConfig
```

Instantiate a BearerConfig object using a bearer token.

**Arguments**:

* `token` - The bearer token.
* `requests_settings` - The requests settings for all outgoing network requests.
* `domain` - Base domain for the endpoints

**Returns**:

* `BearerConfig` - The bearer token configuration.


# Constants.enums
Source: https://docs.encord.com/sdk-documentation/sdk-references/constants.enums



## DataType Objects

```python theme={"dark"}
class DataType(StringEnum)
```

Enumeration of supported data types for labeling and storage.

Values:
video
img\_group
dicom
image
dicom\_study
nifti
audio
time\_series
plain\_text
pdf
group
scene


# Dataset
Source: https://docs.encord.com/sdk-documentation/sdk-references/dataset



## Dataset Objects

```python theme={"dark"}
class Dataset()
```

Access dataset-related data and manipulate the dataset.

#### dataset\_hash

```python theme={"dark"}
@property
def dataset_hash() -> str
```

Get the dataset hash (i.e. the Dataset ID).

**Returns**:

* `str` - The dataset hash.

#### title

```python theme={"dark"}
@property
def title() -> str
```

Get the title of the dataset.

**Returns**:

* `str` - The title of the dataset.

#### description

```python theme={"dark"}
@property
def description() -> str
```

Get the description of the dataset.

**Returns**:

* `str` - The description of the dataset.

#### storage\_location

```python theme={"dark"}
@property
def storage_location() -> StorageLocation
```

Get the storage location of the dataset.

**Returns**:

* `StorageLocation` - The storage location of the dataset.

#### backing\_folder\_uuid

```python theme={"dark"}
@property
def backing_folder_uuid() -> Optional[UUID]
```

Get the UUID of the backing folder.

**Returns**:

* `Optional[UUID]` - The UUID of the backing folder, if any.

#### data\_rows

```python theme={"dark"}
@property
def data_rows() -> List[DataRow]
```

Get the data rows of the dataset.

Part of the response of this function can be configured by the
[set\_access\_settings()](/sdk-documentation/sdk-references/dataset#set_access_settings) method.

```
    dataset.set_access_settings(DatasetAccessSettings(fetch_client_metadata=True))
    print(dataset.data_rows)
```

**Returns**:

* `List[DataRow]` - A list of DataRow objects.

**Raises**:

* `DatasetError` - If the dataset was fetched with `include_data_rows=False`. In that case
  the data rows were never loaded, so returning an empty list here would be
  misleading. Use [list\_data\_rows()](/sdk-documentation/sdk-references/dataset#list_data_rows) to page through rows,
  or refetch the dataset with `include_data_rows=True`.

#### list\_data\_rows

```python theme={"dark"}
def list_data_rows(title_eq: Optional[str] = None,
                   title_like: Optional[str] = None,
                   created_before: Optional[Union[str, datetime]] = None,
                   created_after: Optional[Union[str, datetime]] = None,
                   data_types: Optional[List[DataType]] = None,
                   data_hashes: Optional[List[str]] = None) -> List[DataRow]
```

Retrieve dataset rows (pointers to data, labels).

**Arguments**:

* `title_eq` - Optional exact title row filter.
* `title_like` - Optional fuzzy title row filter; SQL syntax.
* `created_before` - Optional datetime row filter.
* `created_after` - Optional datetime row filter.
* `data_types` - Optional data types row filter.
* `data_hashes` - Optional list of individual data unit hashes to include.

**Returns**:

* `List[DataRow]` - A list of DataRow objects that match the filter.

**Raises**:

* `AuthorisationError` - If the dataset API key is invalid.
* `ResourceNotFoundError` - If no dataset exists by the specified dataset EntityId.
* `UnknownError` - If an error occurs while retrieving the dataset.

#### refetch\_data

```python theme={"dark"}
def refetch_data() -> None
```

Refetch the dataset properties.

The Dataset class will only fetch its properties once. Use this function if you suspect the state of those
properties to be outdated.

#### get\_dataset

```python theme={"dark"}
def get_dataset() -> OrmDataset
```

Get the dataset instance.

This function is exposed for convenience. You are encouraged to use the property accessors instead.

**Returns**:

* `OrmDataset` - The dataset instance.

#### set\_access\_settings

```python theme={"dark"}
def set_access_settings(dataset_access_settings: DatasetAccessSettings,
                        *,
                        refetch_data: bool = True) -> None
```

Set access settings for the dataset.

**Arguments**:

* `dataset_access_settings` - The access settings to use going forward.
* `refetch_data` - Whether a `refetch_data()` call should follow the update of the dataset access settings.

#### add\_users

```python theme={"dark"}
def add_users(user_emails: List[str],
              user_role: DatasetUserRole) -> List[DatasetUser]
```

Add users to the dataset.

If the user already exists in the Dataset, this operation succeeds but the `user_role` remains unchanged. The
existing `user_role` is reflected in the `DatasetUser` instance returned.

**Arguments**:

* `user_emails` - List of user emails to be added.
* `user_role` - The user role to assign to all users.

**Returns**:

* `List[DatasetUser]` - A list of DatasetUser instances reflecting the added users.

#### list\_users

```python theme={"dark"}
def list_users() -> Iterable[DatasetUser]
```

List all users that have access to the dataset.

**Returns**:

* `Iterable[DatasetUser]` - An iterable of DatasetUser instances.

#### remove\_users

```python theme={"dark"}
def remove_users(user_emails: List[str]) -> None
```

Remove users from the dataset by email address.

Emails that do not have access to the dataset are ignored.

**Arguments**:

* `user_emails` - The email addresses of the users to remove.

#### list\_groups

```python theme={"dark"}
def list_groups() -> Iterable[DatasetGroup]
```

List all groups that have access to the dataset.

**Returns**:

* `Iterable[DatasetGroup]` - An iterable of DatasetGroup instances.

#### add\_group

```python theme={"dark"}
def add_group(group_hash: Union[List[UUID], UUID],
              user_role: DatasetUserRole) -> None
```

Add a group to the dataset.

**Arguments**:

* `group_hash` - List of group hashes to be added.
* `user_role` - The user role that the group will be given.

**Returns**:

None

#### remove\_group

```python theme={"dark"}
def remove_group(group_hash: Union[List[UUID], UUID]) -> None
```

Remove a group from the dataset.

**Arguments**:

* `group_hash` - List of group hashes to be removed.

**Returns**:

None

#### upload\_video

```python theme={"dark"}
def upload_video(
        file_path: Union[str, Path],
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        title: Optional[str] = None,
        folder: Optional[Union[UUID, StorageFolder]] = None) -> Video
```

Upload a video to Encord storage.

**Arguments**:

* `file_path` - Path to the video, e.g., '/home/user/data/video.mp4'.
* `cloud_upload_settings` - Settings for uploading data into the cloud. Change this object to overwrite the default values.
* `title` - The video title. If unspecified, this will be the file name. This title should include an extension. For example: "encord\_video.mp4".
* `folder` - When uploading to a non-mirror dataset, you have to specify the folder to store the file in. This can be either a [StorageFolder](/sdk-documentation/sdk-references/storage#storagefolder-objects) instance or the UUID of the folder.

**Returns**:

* `Video` - An object describing the created video, see [Video](/sdk-documentation/sdk-references/orm.dataset#video-objects).

**Raises**:

* `UploadOperationNotSupportedError` - If trying to upload to external datasets (e.g., S3/GPC/Azure).

#### create\_image\_group

```python theme={"dark"}
def create_image_group(
        file_paths: Iterable[Union[str, Path]],
        max_workers: Optional[int] = None,
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        title: Optional[str] = None,
        *,
        create_video: bool = True,
        folder: Optional[Union[UUID,
                               StorageFolder]] = None) -> List[ImageGroup]
```

Create an image group in Encord storage.

Choose this type of image upload for sequential images. Else, you can choose the [upload\_image()](/sdk-documentation/sdk-references/dataset#upload_image) function.

**Arguments**:

* `file_paths` - A list of paths to images, e.g., \['/home/user/data/img1.png', '/home/user/data/img2.png'].
* `max_workers` - DEPRECATED: This argument will be ignored.
* `cloud_upload_settings` - Settings for uploading data into the cloud. Change this object to overwrite the default values.
* `title` - The title of the image group. If unspecified, this will be randomly generated for you. This title should NOT include an extension. For example, "encord\_image\_group".
* `create_video` - A flag specifying how image groups are stored. If `True`, a compressed video will be created from the image groups. `True` was the previous default support. If `False`, the images are saved as a sequence of images.
* `folder` - When uploading to a non-mirror dataset, you have to specify the folder to store the file in. This can be either a [StorageFolder](/sdk-documentation/sdk-references/storage#storagefolder-objects) instance or the UUID of the folder.

**Returns**:

* `List[ImageGroup]` - A list containing the object(s) describing the created data unit(s). See [ImageGroup](/sdk-documentation/sdk-references/orm.dataset#imagegroup-objects).

**Raises**:

* `UploadOperationNotSupportedError` - If trying to upload to external datasets (e.g., S3/GPC/Azure).
* `InvalidArgumentError` - If the folder is specified, but the dataset is a mirror dataset.

#### create\_dicom\_series

```python theme={"dark"}
def create_dicom_series(
        file_paths: Union[Collection[str], Collection[Path],
                          Collection[Union[Path, str]]],
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        title: Optional[str] = None,
        folder: Optional[Union[UUID, StorageFolder]] = None) -> Dict
```

Upload a DICOM series to Encord storage.

**Arguments**:

* `file_paths` - A collection of paths to DICOM files. Example: \['/home/user/data/DICOM\_1.dcm', '/home/user/data/DICOM\_2.dcm']
* `cloud_upload_settings` - Settings for uploading data into the cloud. Change this object to overwrite the default values.
* `title` - The title of the DICOM series. If unspecified, a random title will be generated. This title should NOT include an extension. Example: "encord\_image\_group"
* `folder` - When uploading to a non-mirror dataset, specify the folder to store the file in. This can be either a `StorageFolder` instance or the UUID of the folder.

**Returns**:

A dictionary describing the created series.

**Raises**:

* `UploadOperationNotSupportedError` - If trying to upload to external datasets (e.g., S3/GPC/Azure).
* `InvalidArgumentError` - If the folder is specified, but the dataset is a mirror dataset.

#### upload\_image

```python theme={"dark"}
def upload_image(
        file_path: Union[Path, str],
        title: Optional[str] = None,
        cloud_upload_settings: CloudUploadSettings = CloudUploadSettings(),
        folder: Optional[Union[UUID, StorageFolder]] = None) -> Image
```

Upload a single image to Encord storage. For sequential images, consider creating an image group
using the [create\_image\_group()](/sdk-documentation/sdk-references/dataset#create_image_group) function.

**Arguments**:

* `file_path` - The file path to the image.
* `title` - The image title. If unspecified, the file name will be used. This title should include an extension. Example: "encord\_image.png"
* `cloud_upload_settings` - Settings for uploading data into the cloud. Change this object to overwrite the default values.
* `folder` - When uploading to a non-mirror dataset, specify the folder to store the file in. This can be either a `StorageFolder` instance or the UUID of the folder.

**Returns**:

Uploaded Image object.

#### link\_items

```python theme={"dark"}
def link_items(
    item_uuids: List[UUID],
    duplicates_behavior: DataLinkDuplicatesBehavior = DataLinkDuplicatesBehavior
    .SKIP
) -> List[DataRow]
```

Link storage items to the dataset, creating new data rows.

**Arguments**:

* `item_uuids` - List of item UUIDs to link to the dataset.
* `duplicates_behavior` - The behavior to follow when encountering duplicates. Defaults to `SKIP`. See also [DataLinkDuplicatesBehavior](/sdk-documentation/sdk-references/orm.dataset#datalinkduplicatesbehavior-objects).

**Returns**:

List of DataRow objects representing linked items.

#### delete\_data

```python theme={"dark"}
def delete_data(data_hashes: Union[List[str], str])
```

Delete a video/image group from a dataset.

**Arguments**:

* `data_hashes` - List of hashes of the videos/image\_groups you'd like to delete. All should belong to the same dataset.

#### add\_private\_data\_to\_dataset

```python theme={"dark"}
def add_private_data_to_dataset(
        integration_id: str,
        private_files: Union[str, Dict, Path, TextIO],
        ignore_errors: bool = False) -> AddPrivateDataResponse
```

Append data hosted on a private cloud to an existing dataset.

For a more complete example of safe uploads, please follow the guide found in our docs under
:ref:`https://python.docs.encord.com/tutorials/datasets.html#adding-data-from-a-private-cloud`

**Arguments**:

* `integration_id` - The `EntityId` of the cloud integration you wish to use.
* `private_files` - A path to a JSON file, JSON string, Python dictionary, or a `Path` object containing the files you wish to add.
* `ignore_errors` - When set to `True`, prevent individual errors from stopping the upload process.

**Returns**:

List of DatasetDataInfo objects containing data\_hash and title.

#### add\_private\_data\_to\_dataset\_start

```python theme={"dark"}
def add_private_data_to_dataset_start(
        integration_id: str,
        private_files: Union[str, Dict, Path, TextIO],
        ignore_errors: bool = False,
        *,
        folder: Optional[Union[StorageFolder, UUID]] = None) -> str
```

Append data hosted on a private cloud to an existing dataset.

This method initializes the upload in Encord's backend.
Once the upload ID has been returned, you can exit the terminal
while the job continues uninterrupted.

You can check upload job status at any point using
the [add\_private\_data\_to\_dataset\_get\_result()](/sdk-documentation/sdk-references/dataset#add_private_data_to_dataset_get_result) method.
This can be done in a separate Python session to the one
where the upload was initialized.

**Arguments**:

* `integration_id` - The `EntityId` of the cloud integration you wish to use.
  private\_files:A path to a JSON file, JSON string, Python dictionary, or a `Path` object containing the files you wish to add.
* `ignore_errors` - When set to `True`, prevent individual errors from stopping the upload process.
* `folder` - When uploading to a non-mirror dataset, specify the folder to store the file in. This can be either a `StorageFolder` instance or the UUID of the folder.

**Returns**:

UUID Identifier of the upload job.
This ID enables the user to track the job progress via SDK or web app.

#### add\_private\_data\_to\_dataset\_get\_result

```python theme={"dark"}
def add_private_data_to_dataset_get_result(
        upload_job_id: str,
        timeout_seconds: int = 7 * 24 * 60 * 60) -> DatasetDataLongPolling
```

Fetch data upload status, perform long polling process for `timeout_seconds`.

**Arguments**:

* `upload_job_id` - UUID Identifier of the upload job. This ID enables the user to track the job progress via SDK or web app.
* `timeout_seconds` - Number of seconds the method will wait while waiting for a response. If `timeout_seconds == 0`, only a single checking request is performed. Response will be immediately returned.

**Returns**:

Response containing details about job status, errors, and progress.

#### update\_data\_item

```python theme={"dark"}
@deprecated(version="0.1.192", alternative="encord.storage.StorageItem.update")
def update_data_item(data_hash: str, new_title: str) -> bool
```

DEPRECATED: Use [update()](/sdk-documentation/sdk-references/storage#update) to update the
:attr:`encord.storage.StorageItem.name` of the underlying [StorageItem](/sdk-documentation/sdk-references/orm.storage#storageitem-objects).

Update a data item.

**Arguments**:

* `data_hash` - Data hash of the item being updated.
* `new_title` - New title of the data item being updated.

**Returns**:

Boolean indicating whether the update was successful.

#### re\_encode\_data

```python theme={"dark"}
def re_encode_data(data_hashes: List[str])
```

Launch an async task that can re-encode a list of videos.

**Arguments**:

* `data_hashes` - List of hashes of the videos you'd like to re-encode. All should belong to the same dataset.

**Returns**:

Entity ID of the async task launched.

#### re\_encode\_data\_status

```python theme={"dark"}
def re_encode_data_status(job_id: int)
```

Returns the status of an existing async task aimed at re-encoding videos.

**Arguments**:

* `job_id` - ID of the async task that was launched to re-encode the videos.

**Returns**:

Object containing the status of the task, along with info about the new encoded videos
in case the task has been completed.

#### get\_cloud\_integrations

```python theme={"dark"}
@deprecated(version="0.1.154",
            alternative="EncordUserClient.get_cloud_integrations")
def get_cloud_integrations() -> List[CloudIntegration]
```

Retrieve a list of cloud integrations configured in Encord.

**Returns**:

List of CloudIntegration objects representing configured cloud integrations.


# Exceptions
Source: https://docs.encord.com/sdk-documentation/sdk-references/exceptions



## EncordException Objects

```python theme={"dark"}
class EncordException(Exception)
```

Base class for all exceptions.

## InitialisationError Objects

```python theme={"dark"}
class InitialisationError(EncordException)
```

Exception thrown when API key fails to initialize.

## AuthenticationError Objects

```python theme={"dark"}
class AuthenticationError(EncordException)
```

Exception thrown when API key fails authentication.

## AuthorisationError Objects

```python theme={"dark"}
class AuthorisationError(EncordException)
```

Exception thrown when access is unauthorized.
(E.g. access to a data asset or method).

## ResourceNotFoundError Objects

```python theme={"dark"}
class ResourceNotFoundError(EncordException)
```

Exception thrown when a requested resource is not found.
(E.g. label, data asset).

## TimeOutError Objects

```python theme={"dark"}
class TimeOutError(EncordException)
```

Exception thrown when a request times out.

## RequestException Objects

```python theme={"dark"}
class RequestException(EncordException)
```

Ambiguous exception while handling request.

## RateLimitExceededError Objects

```python theme={"dark"}
class RateLimitExceededError(EncordException)
```

Exception raised when requests exceed the Encord API rate limit.

## PayloadTooLargeError Objects

```python theme={"dark"}
class PayloadTooLargeError(EncordException)
```

Exception raised when request payload exceeds the maximum allowed size.

## UnknownException Objects

```python theme={"dark"}
class UnknownException(EncordException)
```

Unknown error.

## InvalidDateFormatError Objects

```python theme={"dark"}
class InvalidDateFormatError(EncordException)
```

Invalid date format error

## MethodNotAllowedError Objects

```python theme={"dark"}
class MethodNotAllowedError(EncordException)
```

Exception thrown when HTTP method is not allowed.

## OperationNotAllowed Objects

```python theme={"dark"}
class OperationNotAllowed(EncordException)
```

Exception thrown when a read/write operation is not allowed.
The API key blocks the operation.

## AnswerDictionaryError Objects

```python theme={"dark"}
class AnswerDictionaryError(EncordException)
```

Exception thrown when answer dictionaries are incomplete.
Occurs when an object or classification is missing.

## CorruptedLabelError Objects

```python theme={"dark"}
class CorruptedLabelError(EncordException)
```

Exception thrown when a label is corrupted.
(E.g. the frame labels have more frames than the video).

## FileTypeNotSupportedError Objects

```python theme={"dark"}
class FileTypeNotSupportedError(EncordException)
```

Exception thrown when a file type is not supported.
Supported file types are: image/jpeg, image/png, video/webm, video/mp4.

## FileSizeNotSupportedError Objects

```python theme={"dark"}
class FileSizeNotSupportedError(EncordException)
```

Exception thrown when the combined size of the input files is larger than the supported limit.

## FeatureDoesNotExistError Objects

```python theme={"dark"}
class FeatureDoesNotExistError(EncordException)
```

If a feature uid does not exist in a given project ontology.

## ModelWeightsInconsistentError Objects

```python theme={"dark"}
class ModelWeightsInconsistentError(EncordException)
```

Exception thrown when an attempted model training iteration has a different
type of weights than what is recorded (i.e. if type of model\_hash (uid) is faster\_rcnn,
but is attempted trained with different model weights).

## ModelFeaturesInconsistentError Objects

```python theme={"dark"}
class ModelFeaturesInconsistentError(EncordException)
```

If a feature type is different than what is supported by the model (e.g. if
creating a classification model using a bounding box).

## UploadOperationNotSupportedError Objects

```python theme={"dark"}
class UploadOperationNotSupportedError(EncordException)
```

Exception thrown when trying to upload a video/image group to non-Encord storage dataset

## DetectionRangeInvalidError Objects

```python theme={"dark"}
class DetectionRangeInvalidError(EncordException)
```

Exception thrown when a detection range is invalid.
(E.g. negative or higher than num frames in video).

## InvalidAlgorithmError Objects

```python theme={"dark"}
class InvalidAlgorithmError(EncordException)
```

Exception thrown when invalid labeling algorithm name is sent.

## ResourceExistsError Objects

```python theme={"dark"}
class ResourceExistsError(EncordException)
```

Exception thrown when trying to re-create a resource.
Avoids overriding existing work.

## DuplicateSshKeyError Objects

```python theme={"dark"}
class DuplicateSshKeyError(EncordException)
```

Exception thrown when using an SSH key that was added twice to the platform.

## SshKeyNotFound Objects

```python theme={"dark"}
class SshKeyNotFound(EncordException)
```

Exception thrown when using an SSH key that was not added to the platform.

## InvalidArgumentsError Objects

```python theme={"dark"}
class InvalidArgumentsError(EncordException)
```

Exception thrown when the arguments are invalid.

## GenericServerError Objects

```python theme={"dark"}
class GenericServerError(EncordException)
```

The server has reported an error which is not recognized by this SDK version. Try upgrading the SDK version to
see the precise error that is reported.

## CloudUploadError Objects

```python theme={"dark"}
class CloudUploadError(EncordException)
```

The upload to the cloud was not successful

## MultiLabelLimitError Objects

```python theme={"dark"}
class MultiLabelLimitError(EncordException)
```

Too many labels were requested

## LabelRowError Objects

```python theme={"dark"}
class LabelRowError(EncordException)
```

An error thrown when the construction of a LabelRow class is invalid.

## DatasetError Objects

```python theme={"dark"}
class DatasetError(EncordException)
```

An error thrown when a Dataset is used in an invalid state.

## OntologyError Objects

```python theme={"dark"}
class OntologyError(EncordException)
```

An error thrown when using the ontology class with an error.

## WrongProjectTypeError Objects

```python theme={"dark"}
class WrongProjectTypeError(CordException)
```

An error thrown when project type does not match the operation
E.g. when TMS2 specific operations are attempted on non-TMS2 project

## BundledMoveWorkflowTasksPayloadError Objects

```python theme={"dark"}
class BundledMoveWorkflowTasksPayloadError(EncordException)
```

An error thrown when an invalid item is added to the bundle to move workflow tasks


# Filter preset
Source: https://docs.encord.com/sdk-documentation/sdk-references/filter_preset



## FilterPreset Objects

```python theme={"dark"}
class FilterPreset()
```

Represents preset in Index.
Preset is a group of filters persisted which can be reused for faster data curation.

#### uuid

```python theme={"dark"}
@property
def uuid() -> UUID
```

Get the preset uuid (i.e. the preset ID).

**Returns**:

* `str` - The preset uuid.

#### name

```python theme={"dark"}
@property
def name() -> str
```

Get the preset name

**Returns**:

* `str` - The preset name.

#### description

```python theme={"dark"}
@property
def description() -> Optional[str]
```

Get the preset description

**Returns**:

* `Optional[str]` - The preset description.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> Optional[datetime]
```

Get the preset creation timestamp

**Returns**:

* `Optional[datetime]` - The preset creation timestamp.

#### last\_updated\_at

```python theme={"dark"}
@property
def last_updated_at() -> Optional[datetime]
```

Get the preset last update timestamp

**Returns**:

* `Optional[datetime]` - The preset last update timestamp.

#### update\_preset

```python theme={"dark"}
def update_preset(name: Optional[str] = None,
                  description: Optional[str] = None,
                  filter_preset_json: Optional[dict] = None) -> None
```

Update the preset's definition.

**Arguments**:

* `name` *Optional\[str]* - The new name for the preset.
* `description` *Optional\[str]* - The new description for the preset.
* `filter_preset_json` *Optional\[dict]* - The new filters for the preset in their raw json format.

## ProjectFilterPreset Objects

```python theme={"dark"}
class ProjectFilterPreset()
```

Represents Active filter presets.

#### uuid

```python theme={"dark"}
@property
def uuid() -> UUID
```

Get the filter preset unique identifier (UUID).

**Returns**:

* `UUID` - The filter preset UUID.

#### name

```python theme={"dark"}
@property
def name() -> str
```

Get the filter preset name.

**Returns**:

* `str` - The collection name.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> Optional[datetime]
```

Get the filter preset creation timestamp.

**Returns**:

* `Optional[datetime]` - The timestamp when the filter preset was created, or None if not available.

#### updated\_at

```python theme={"dark"}
@property
def updated_at() -> Optional[datetime]
```

Get the filter preset last edit timestamp.

**Returns**:

* `Optional[datetime]` - The timestamp when the filter preset was last edited, or None if not available.

#### project\_hash

```python theme={"dark"}
@property
def project_hash() -> UUID
```

Get the project hash of the filter preset.

**Returns**:

* `UUID` - The project hash of the filter preset.


# Group
Source: https://docs.encord.com/sdk-documentation/sdk-references/group



## Group Objects

```python theme={"dark"}
class Group()
```

Represents a group of users within an organization.

Groups can be granted access to projects, datasets, ontologies, and storage
folders, and are a convenient way to manage permissions for several users at
once. Obtain instances of this class via
[create\_group()](/sdk-documentation/sdk-references/user_client#create_group),
[get\_group()](/sdk-documentation/sdk-references/user_client#get_group), or
[list\_groups()](/sdk-documentation/sdk-references/user_client#list_groups).

#### group\_hash

```python theme={"dark"}
@property
def group_hash() -> UUID
```

Get the group unique identifier (UUID).

**Returns**:

* `UUID` - The group UUID.

#### name

```python theme={"dark"}
@property
def name() -> str
```

Get the group name.

**Returns**:

* `str` - The group name.

#### description

```python theme={"dark"}
@property
def description() -> str
```

Get the group description.

**Returns**:

* `str` - The group description.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> datetime
```

Get the group creation timestamp.

**Returns**:

* `datetime` - The timestamp when the group was created.

#### update\_group

```python theme={"dark"}
def update_group(name: Optional[str] = None,
                 description: Optional[str] = None) -> None
```

Update the group's name and/or description.

At least one of `name` or `description` must be provided. Fields left
as `None` are not modified.

**Arguments**:

* `name` - The new name for the group.
* `description` - The new description for the group.

#### list\_users

```python theme={"dark"}
def list_users() -> Iterator[GroupUser]
```

List the users belonging to the group.

**Returns**:

* `Iterator[GroupUser]` - The users that belong to the group.

#### add\_users

```python theme={"dark"}
def add_users(user_emails: List[str]) -> List[GroupUser]
```

Add users to the group by email address.

All emails must belong to existing members of the organization; the
request fails with an authorization error if any do not. To add
someone to the organization first, see
[add\_organisation\_user()](/sdk-documentation/sdk-references/user_client#add_organisation_user).

**Arguments**:

* `user_emails` - The email addresses of the users to add.

**Returns**:

* `List[GroupUser]` - The full list of users in the group after the addition.

#### remove\_users

```python theme={"dark"}
def remove_users(user_emails: List[str]) -> None
```

Remove users from the group by email address.

Emails that are not in the group are ignored.

**Arguments**:

* `user_emails` - The email addresses of the users to remove.


# Http.bundle
Source: https://docs.encord.com/sdk-documentation/sdk-references/http.bundle



## BundlablePayload Objects

```python theme={"dark"}
class BundlablePayload(Protocol[BundlablePayloadT])
```

All payloads that work with bundles need to provide "add" method
that would allow bundler to combine multiple payloads into one or few aggregates.

## Bundle Objects

```python theme={"dark"}
class Bundle()
```

This class allows to perform operations in bundles to improve performance by reducing number of network calls.

It is not supposed to be instantiated directly by a user. Use [create\_bundle()](/sdk-documentation/sdk-references/project#create_bundle)
method to initiate bundled operations.

To execute batch you can either call  [execute()](/sdk-documentation/sdk-references/http.bundle#execute) directly, or use a Context Manager.

#### add

```python theme={"dark"}
def add(operation: Callable[..., List[R]],
        result_mapper: Optional[BundleResultMapper[R]],
        payload: BundlablePayloadT, limit: int) -> None
```

This is an internal method and normally is not supposed to be used externally.

Adds an operation to a bundle for delayed execution.

#### execute

```python theme={"dark"}
def execute() -> None
```

Executes all scheduled operations in bundles and populates results


# Http.constants
Source: https://docs.encord.com/sdk-documentation/sdk-references/http.constants



#### DEFAULT\_READ\_TIMEOUT

In seconds

#### DEFAULT\_WRITE\_TIMEOUT

In seconds

#### DEFAULT\_CONNECT\_TIMEOUT

In seconds

## RequestsSettings Objects

```python theme={"dark"}
@dataclass
class RequestsSettings()
```

The settings for all outgoing network requests. These apply for each individual request.

#### max\_retries

Number of allowed retries when a request is sent. It only affects idempotent retryable requests.

#### backoff\_factor

With each retry, there will be a sleep of backoff\_factor \* (2 \*\* (retry\_number - 1) )

#### connection\_retries

Number of allowed retries to establish TCP connection when a request is sent.

#### connect\_timeout

Maximum number of seconds from connection establishment to the first byte of response received

#### read\_timeout

Maximum number of seconds to obtain full response

#### write\_timeout

Maximum number of seconds to send request payload

#### trace\_id\_provider

Function that supplies trace id for every request issued by the library. Random if not provided.


# Http.error utils
Source: https://docs.encord.com/sdk-documentation/sdk-references/http.error_utils



#### check\_error\_response

```python theme={"dark"}
def check_error_response(response,
                         context: Optional[RequestContext] = None,
                         payload: Any = None)
```

Checks server response.
Called if HTTP response status code is an error response.


# Http.querier
Source: https://docs.encord.com/sdk-documentation/sdk-references/http.querier



## Querier Objects

```python theme={"dark"}
class Querier()
```

Querier for DB get/post requests.

#### basic\_getter

```python theme={"dark"}
def basic_getter(response_type: Type[T],
                 uid: UIDType = None,
                 payload: PayloadType = None,
                 retryable=True) -> T
```

Single DB object getter.

#### basic\_delete

```python theme={"dark"}
def basic_delete(query_type: Type[T], uid: UIDType = None, retryable=False)
```

Single DB object getter.

#### basic\_setter

```python theme={"dark"}
def basic_setter(query_type: Type[T],
                 uid: UIDType,
                 payload: PayloadType,
                 retryable=False)
```

Single DB object setter.

#### basic\_put

```python theme={"dark"}
def basic_put(query_type,
              uid,
              payload: PayloadType,
              retryable: bool = True,
              enable_logging: bool = True)
```

Single DB object put request.


# Http.request
Source: https://docs.encord.com/sdk-documentation/sdk-references/http.request



## Request Objects

```python theme={"dark"}
class Request()
```

Request object. Takes query parameters and prepares them for execution.


# Http.utils
Source: https://docs.encord.com/sdk-documentation/sdk-references/http.utils



#### CACHE\_DURATION\_IN\_SECONDS

1 day

## CloudUploadSettings Objects

```python theme={"dark"}
@dataclass
class CloudUploadSettings()
```

Settings for uploading data into GCP cloud storage.

These apply for each individual upload and will overwrite
the [RequestsSettings()](/sdk-documentation/sdk-references/http.constants#requestssettings-objects) defined during
[EncordUserClient](/sdk-documentation/sdk-references/user_client#encorduserclient-objects) creation.

#### max\_retries

Maximum number of allowed retries when uploading a file.

#### backoff\_factor

Factor used to calculate exponential backoff between retries.

The delay before each retry is computed as:
`backoff_factor * (2 ** (retry_number - 1))`.

#### allow\_failures

Whether to allow partial failures during upload.

If set to True, the upload will proceed even if some items fail
after all retries. Failed uploads will be logged, and the process
will continue. This is useful for large batch uploads where a few
failures are acceptable.

#### get\_batches

```python theme={"dark"}
def get_batches(iterable: List, n: int) -> List[List]
```

Split an iterable into fixed-size batches.

**Arguments**:

* `iterable` *List* - The input list to be split.
* `n` *int* - The maximum size of each batch.

**Returns**:

* `List[List]` - A list of lists where each sublist represents a batch.

**Notes**:

This can be replaced with `itertools.batched <https://docs.python.org/3/library/itertools.html#itertools.batched>`\_\` in Python 3.12+.

## UploadToSignedUrlFailure Objects

```python theme={"dark"}
@dataclass
class UploadToSignedUrlFailure()
```

Details of a failed upload attempt to a signed URL.

#### exception

The exception instance raised during the failed upload.

#### file\_path

Path to the file that failed to upload.

#### title

Title or identifier associated with the file.

#### signed\_url

The signed URL that the file upload was attempted against.

#### upload\_to\_signed\_url\_list\_for\_single\_file

```python theme={"dark"}
def upload_to_signed_url_list_for_single_file(
        failures: List[UploadToSignedUrlFailure],
        file_path: Union[str, Path],
        title: str,
        signed_url: str,
        upload_item_type: StorageItemType,
        max_retries: int,
        backoff_factor: float,
        upload_headers: Optional[Dict[str, str]] = None) -> None
```

Attempt to upload a single file to a signed URL, appending failures if any occur.

**Arguments**:

* `failures` *List\[UploadToSignedUrlFailure]* - A list to append failures to.
* `file_path` *Union\[str, Path]* - Path of the file to upload.
* `title` *str* - Title or identifier for the file.
* `signed_url` *str* - The signed URL to upload the file to.
* `upload_item_type` *StorageItemType* - The type of the file being uploaded.
* `max_retries` *int* - Maximum number of retries in case of failure.
* `backoff_factor` *float* - Backoff factor for retry delays.
* `upload_headers` *Optional\[Dict\[str, str]]* - Backend-specified headers
  (e.g. Azure's `x-ms-blob-type`) to forward on the PUT.

## UploadPresignedUrlsGetParams Objects

```python theme={"dark"}
class UploadPresignedUrlsGetParams(BaseDTO)
```

Parameters for requesting presigned URLs for file uploads.

#### count

Number of presigned URLs to request, typically matching the batch size of files.

#### upload\_item\_type

The type of item being uploaded (e.g., IMAGE, VIDEO, AUDIO, DICOM).

#### upload\_to\_signed\_url\_list

```python theme={"dark"}
def upload_to_signed_url_list(
        file_paths: Iterable[Union[str, Path]], config: BaseConfig,
        api_client: ApiClient, upload_item_type: StorageItemType,
        cloud_upload_settings: CloudUploadSettings) -> List[Dict]
```

Upload multiple files to signed URLs and return upload results.

**Arguments**:

* `file_paths` *Iterable\[Union\[str, Path]]* - Paths of files to upload.
* `config` *BaseConfig* - Configuration object with request settings.
* `api_client` *ApiClient* - API client used to fetch presigned URLs.
* `upload_item_type` *StorageItemType* - Type of items being uploaded.
* `cloud_upload_settings` *CloudUploadSettings* - Upload configuration.

**Returns**:

* `List[Dict]` - A list of dictionaries containing upload metadata:
  * `data_hash` (str): Unique identifier for the file.
  * `file_link` (str): Link to the uploaded file in storage.
  * `title` (str): File name or title.

**Raises**:

* `EncordException` - If any file path does not exist.
* `CloudUploadError` - If uploads fail and `allow_failures` is False.

#### download\_signed\_urls\_as\_json

```python theme={"dark"}
def download_signed_urls_as_json(
        urls: Iterable[str], *,
        requests_settings: RequestsSettings) -> Dict[str, Any]
```

Concurrently GET each URL and JSON-decode the body.

Returns a mapping of `url -> decoded JSON` for the URLs that resolved successfully. Transient
failures (5xx, 429, connection resets, timeouts) are retried with exponential back off and
jitter via the underlying session. Any URL that still fails — a non-200 status (e.g. an expired
or missing object), an exhausted retry, or a body that won't JSON-parse — is omitted from the
result rather than raised, so a single bad URL never fails the whole batch and callers can
treat absence as "no content for this URL". Duplicate and falsy URLs are ignored.


# Http.v2.api client
Source: https://docs.encord.com/sdk-documentation/sdk-references/http.v2.api_client



## ApiClient Objects

```python theme={"dark"}
class ApiClient()
```

#### get\_bound\_operation

```python theme={"dark"}
def get_bound_operation(operation: Callable) -> Callable
```

Wrap a function to bind it to the current API client instance (via a named parameter). This is useful for
bundling, as the 'Bundle' groups operations based on the 'operation' function, which means that if
you use an entity object method as the operation, then it will not be grouped with other similar operations.


# Http.v2.error utils
Source: https://docs.encord.com/sdk-documentation/sdk-references/http.v2.error_utils



#### handle\_error\_response

```python theme={"dark"}
def handle_error_response(status_code: int,
                          response_headers: Mapping[str, str],
                          message: str | None = None,
                          context: RequestContext | None = None)
```

Checks server response.
Called if HTTP response status code is an error response.


# Issues.issue client
Source: https://docs.encord.com/sdk-documentation/sdk-references/issues.issue_client



## IssueFrameRange Objects

```python theme={"dark"}
class IssueFrameRange(BaseDTO)
```

Represents a range of frames \[start, end] inclusive

## SceneCoordinateIssue Objects

```python theme={"dark"}
class SceneCoordinateIssue(_BaseIssue)
```

Issue anchored to a 3D coordinate within a scene on a specific frame.

## FrameRangeIssue Objects

```python theme={"dark"}
class FrameRangeIssue(_BaseIssue)
```

Issue anchored to a range of frames

## AnnotationIssue Objects

```python theme={"dark"}
class AnnotationIssue(_BaseIssue)
```

Issue anchored to a specific annotation (label rejection or annotation feedback)

## TaskIssues Objects

```python theme={"dark"}
class TaskIssues()
```

#### list

```python theme={"dark"}
def list() -> Iterable[Issue]
```

Lists all issues (comment threads) for this task.

Returns an iterator of issues anchored to different parts of the data unit:

* FileIssue: Issues anchored to the entire data unit
* FrameIssue: Issues anchored to a specific frame
* CoordinateIssue: Issues anchored to specific 2D coordinates on a frame
* SceneCoordinateIssue: Issues anchored to 3D scene coordinates on a frame
* FrameRangeIssue: Issues anchored to a range of frames
* AnnotationIssue: Issues anchored to a specific annotation

Each issue includes comments, tags, and resolution history.

**Returns**:

* `Iterable[Issue]` - An iterator of Issue objects (discriminated union of all issue types).

**Example**:

```python theme={"dark"}
for issue in task.issues.list():
    if isinstance(issue, FileIssue):
        print(f"File issue: {issue.comments[0].content}")
    elif isinstance(issue, FrameIssue):
        print(f"Frame {issue.frame_index}: {issue.comments[0].content}")
```

#### add\_file\_issue

```python theme={"dark"}
def add_file_issue(comment: str,
                   issue_tags: List[str],
                   space_id: Optional[str] = None) -> None
```

Adds a file issue.

**Arguments**:

* `comment` *str* - The comment for the issue.
* `issue_tags` *List\[str]* - The issue tags for the issue.
* `space_id` *Optional\[str]* - For data units that use spaces (Data Groups and scenes),
  identifies which space the issue is attached to. Leave as `None` for data
  units without spaces.

#### add\_frame\_issue

```python theme={"dark"}
def add_frame_issue(frame_index: int,
                    comment: str,
                    issue_tags: List[str],
                    space_id: Optional[str] = None) -> None
```

Adds a frame issue.

**Arguments**:

* `frame_index` *int* - The index of the frame to add the issue to.
* `comment` *str* - The comment for the issue.
* `issue_tags` *List\[str]* - The issue tags for the issue.
* `space_id` *Optional\[str]* - For data units that use spaces (Data Groups and scenes),
  identifies which space the issue is attached to. Leave as `None` for data
  units without spaces.

#### add\_coordinate\_issue

```python theme={"dark"}
def add_coordinate_issue(frame_index: int,
                         x: float,
                         y: float,
                         comment: str,
                         issue_tags: List[str],
                         space_id: Optional[str] = None) -> None
```

Adds a issue pinned to a coordinate.

**Arguments**:

* `frame_index` *int* - The index of the frame to add the issue to.
* `x` *float* - The x coordinate of the issue.
* `y` *float* - The y coordinate of the issue.
* `comment` *str* - The comment for the issue.
* `issue_tags` *List\[str]* - The issue tags for the issue.
* `space_id` *Optional\[str]* - For data units that use spaces (Data Groups and scenes),
  identifies which space the issue is attached to. Leave as `None` for data
  units without spaces.

#### add\_scene\_coordinate\_issue

```python theme={"dark"}
def add_scene_coordinate_issue(frame_index: int, x: float, y: float, z: float,
                               comment: str, issue_tags: List[str]) -> None
```

Adds an issue pinned to a 3D coordinate in a scene on a specific frame.

**Arguments**:

* `frame_index` *int* - The index of the frame to add the issue to.
* `x` *float* - The x coordinate (in scene space).
* `y` *float* - The y coordinate (in scene space).
* `z` *float* - The z coordinate (in scene space).
* `comment` *str* - The comment for the issue.
* `issue_tags` *List\[str]* - The issue tags for the issue.

#### add\_annotation\_issue

```python theme={"dark"}
def add_annotation_issue(annotation_id: str,
                         comment: str,
                         issue_tags: List[str],
                         frame_ranges: Optional[List[IssueFrameRange]] = None,
                         space_id: Optional[str] = None) -> None
```

Adds an issue anchored to a specific annotation (object or classification instance).

**Arguments**:

* `annotation_id` *str* - The annotation the issue is attached to. This is the
  object instance `object_hash` (or classification instance
  `classification_hash`) of the annotation within this task's data unit.

* `comment` *str* - The comment for the issue.

* `issue_tags` *List\[str]* - The issue tags for the issue.

* `frame_ranges` *Optional\[List\[IssueFrameRange]]* - The frame ranges to pin the issue
  to, each an inclusive `[start, end]` range. Leave as `None` to
  flag the whole annotation instance across every frame it appears on (e.g. a

  wrong attribute value). Provide one or more ranges to target the instance on
  those frames (e.g. a bad contour over a span of frames). A single frame is a
  range where `start == end`.

* `space_id` *Optional\[str]* - For data units that use spaces (Data Groups and scenes),
  identifies which space the annotation belongs to. Leave as `None` for data
  units without spaces.

**Example**:

```python theme={"dark"}
for obj in label_row.get_object_instances():
    # Flag the whole instance (e.g. wrong attribute value):
    if not passes_attribute_qa(obj):
        task.issues.add_annotation_issue(
            annotation_id=obj.object_hash,
            comment="Wrong attribute value",
            issue_tags=["qa-automation"],
        )
    # Flag the instance over a span of frames (e.g. bad contour on frames 30-45):
    task.issues.add_annotation_issue(
        annotation_id=obj.object_hash,
        comment="Bad contour",
        issue_tags=["qa-automation"],
        frame_ranges=[IssueFrameRange(start=30, end=45)],
    )
```

**Raises**:

* `ValueError` - If `frame_ranges` is an empty list (omit it, or pass `None`, to
  target the whole annotation instance) or contains an invalid range where
  `start` is negative or `start > end`.

#### delete

```python theme={"dark"}
def delete(issues: List[Union[Issue, UUID]]) -> None
```

Deletes one or more issues from this task in a single request.

Accepts either `Issue` objects (as returned by `list()`) or raw UUIDs,
mixed freely. Empty input is a no-op.

Permissions: project admins can delete any issue. Issue authors can
delete their own general issues, but annotation issues (label
rejections) can only be deleted by project admins.

The back-end validates the entire batch before deleting anything: if
any issue cannot be deleted (because the caller is not the author and
not a project admin, or the issue doesn't belong to this task's
project), the request raises and NO issues in the batch are deleted.

**Arguments**:

* `issues` - A list of `Issue` objects or `UUID`s to delete.

**Example**:

```python theme={"dark"}
# 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)
```


# Metadata schema
Source: https://docs.encord.com/sdk-documentation/sdk-references/metadata_schema



## MetadataSchemaError Objects

```python theme={"dark"}
class MetadataSchemaError(RuntimeError)
```

Raised when an invariant is violated when mutating metadata schemas

## MetadataSchema Objects

```python theme={"dark"}
class MetadataSchema()
```

A class to manage the metadata schema for an organization.

**Methods:**

save() -> None: Saves the metadata schema to the backend if it has been modified.

#### save

```python theme={"dark"}
def save() -> None
```

Saves the metadata schema to the backend if changes have been made.

#### add\_embedding

```python theme={"dark"}
def add_embedding(k: str, *, size: int) -> None
```

Adds a new embedding to the metadata schema.

**Arguments**:

k : str: The key under which the embedding will be stored in the schema.
size : int: The size of the embedding.

**Raises**:

* `MetadataSchemaError` - If the key `k` is already defined in the schema.

#### add\_geospatial

```python theme={"dark"}
def add_geospatial(k: str) -> None
```

Adds a new geospatial type to the metadata schema.

**Arguments**:

k : str: The key under which the geospatial coordinates will be stored in the schema.

**Raises**:

* `MetadataSchemaError` - If the key `k` is already defined in the schema.

#### add\_enum

```python theme={"dark"}
def add_enum(k: str, *, values: Sequence[str]) -> None
```

Adds a new enum to the metadata schema.

**Arguments**:

k : str: The key under which the enum will be stored in the schema.
values : Sequence\[str]: The set of values for the enum (min 1, max 256).

**Raises**:

* `MetadataSchemaError` - If the key `k` is already defined in the schema.

#### add\_enum\_options

```python theme={"dark"}
def add_enum_options(k: str, *, values: Sequence[str]) -> None
```

Adds extra valid enum values to an existing enum schema.

**Arguments**:

k : str: The key referencing the enum.
values : Sequence\[str]: The set of new values to add to the enum (min 1, max 256).

**Raises**:

* `MetadataSchemaError` - If the key `k` is not defined in the schema or is not an enum.

#### add\_scalar

```python theme={"dark"}
def add_scalar(
    k: str, *, data_type: Union[
        Literal["boolean", "datetime", "number", "uuid", "varchar", "text",
                "string", "long_string"],
        MetadataSchemaScalarType,
    ]
) -> None
```

Sets a simple metadata type for a given key in the schema.

**Arguments**:

k : str: The key for which the metadata type is being set.
data\_type : Literal\["boolean", "datetime", "number", "uuid", "varchar", "text", "string", "long\_string"]
The type of metadata to be associated with the key. Must be a valid identifier.
"string" is an alias of "varchar"
"long\_string" is an alias of "text"

**Raises**:

* `MetadataSchemaError` - If the key `k` is already defined in the schema with a conflicting type.
* `ValueError` - If `data_type` is not a valid type of metadata identifier.

#### set\_scalar

```python theme={"dark"}
def set_scalar(
    k: str, *, data_type: Union[
        Literal["boolean", "datetime", "number", "uuid", "varchar", "text",
                "string", "long_string"],
        MetadataSchemaScalarType,
    ]
) -> None
```

Sets a simple metadata type for a given key in the schema.

Alias of add\_scalar

**Arguments**:

k : str: The key for which the metadata type is being set.
data\_type : Literal\["boolean", "datetime", "number", "uuid", "varchar", "text", "string", "long\_string"]
The type of metadata to be associated with the key. Must be a valid identifier.
"string" is an alias of "varchar"
"long\_string" is an alias of "text"

**Raises**:

* `MetadataSchemaError` - If the key `k` is already defined in the schema with a conflicting type.
* `ValueError` - If `data_type` is not a valid type of metadata identifier.

#### delete\_key

```python theme={"dark"}
def delete_key(k: str, *, hard: bool = False) -> None
```

Delete a metadata key from the schema.

**Arguments**:

k : str: The key for which the metadata type is being deleted.

* `hard` - bool: If the deletion should prevent indexing of this key unconditionally.
  Setting this to true prevents restoring the type definition in the future.

**Raises**:

* `MetadataSchemaError` - If the key `k` is already deleted or not present in the schema

#### restore\_key

```python theme={"dark"}
def restore_key(k: str) -> None
```

Restore a deleted metadata key to its original value.

**Arguments**:

k : str: The key for which the metadata type is to be restored.

**Raises**:

* `MetadataSchemaError` - If the key `k` is not already deleted or not present in the schema

#### keys

```python theme={"dark"}
def keys() -> Sequence[str]
```

Returns a sequence of all keys defined in the metadata schema.

**Returns**:

* `Sequence[str]` - A list of keys present in the metadata schema.

#### has\_key

```python theme={"dark"}
def has_key(k: str) -> bool
```

Check if any definition exists for a key.

**Arguments**:

k : str: The key for which the metadata type is to be retrieved.

#### is\_key\_deleted

```python theme={"dark"}
def is_key_deleted(k: str) -> bool
```

Check if the key is defined as deleted. (Tombstone type)

**Arguments**:

k : str: The key for which the metadata type is to be retrieved.

#### get\_key\_type

```python theme={"dark"}
def get_key_type(
    k: str
) -> Union[Literal["boolean", "datetime", "uuid", "number", "varchar", "text",
                   "embedding", "enum", "geospatial"], None]
```

Retrieves the metadata type associated with a given key.

**Arguments**:

k : str: The key for which the metadata type is to be retrieved.

**Returns**:

Literal\["boolean", "datetime", "uuid", "number", "varchar", "text", "embedding", "enum", "geospatial"]: The metadata type associated with the key `k`.

**Raises**:

* `MetadataSchemaError` - If the key `k` is not supported by the current SDK.

#### get\_embedding\_size

```python theme={"dark"}
def get_embedding_size(k: str) -> int
```

Retrieves size associated with a given embedding.

**Arguments**:

k : str: The key for which the metadata type is to be retrieved.

**Returns**:

* `int` - The size of the embedding

**Raises**:

* `MetadataSchemaError` - If the key `k` is not defined in the schema or is not an embedding

#### get\_enum\_options

```python theme={"dark"}
def get_enum_options(k: str) -> Sequence[str]
```

Retrieves all values associated with a given enum.

**Arguments**:

k : str: The key for which the metadata type is to be retrieved.

**Returns**:

* `Sequence[str]` - The list of all values associated with an enum type.

**Raises**:

* `MetadataSchemaError` - If the key `k` is not defined in the schema or is not an enum.


# Ml models client
Source: https://docs.encord.com/sdk-documentation/sdk-references/ml_models_client



## MlModelsClient Objects

```python theme={"dark"}
class MlModelsClient()
```

Client for interacting with Encord's ML models functionality. This client provides methods
to create, manage, and use machine learning models within Encord, including classification,
object detection, and instance segmentation models.

#### \_\_init\_\_

```python theme={"dark"}
def __init__(api_client: ApiClient) -> None
```

Initialize the ML Models client.

**Arguments**:

* `api_client` - An authenticated ApiClient instance

#### create\_model

```python theme={"dark"}
def create_model(*, features: List[str], model: ModelArchitecture, title: str,
                 description: Optional[str]) -> ModelWithIterations
```

Create a new model in Encord.

**Arguments**:

* `features` - List of feature names that define the model's output layer structure (e.g. \["car", "person"]).
  These features are directly mapped to neurons in the model's final layer and remain fixed across
  all training iterations. The number and names of features cannot be changed without rebuilding
  the model's architecture, since they determine the size and structure of the output layer.
  This fixed structure enables several key capabilities:
  1. Transfer Learning: The model can be retrained on new datasets while preserving its
     learned feature detectors, since the output layer structure stays consistent
  2. Cross-Project Usage: The same model can be used across different projects by mapping
     its fixed features to different ontology features in each project
  3. Flexible Inference: A model trained to detect "vehicle" can be mapped to detect
     "car", "truck" etc. in different projects based on their specific ontologies
* `model` - The architecture type of the model to create
* `title` - Title for the model
* `description` - Optional description for the model

**Returns**:

* `ModelWithIterations` - The created model and its iterations

#### get\_model

```python theme={"dark"}
def get_model(*, model_uuid: UUID) -> ModelWithIterations
```

Get information about a specific model.

**Arguments**:

* `model_uuid` - UUID of the model to get information for

**Returns**:

* `ModelWithIterations` - Information about the requested model

#### list\_models

```python theme={"dark"}
def list_models(*, order_by: ModelsListOrderBy, order_asc: bool,
                query: Optional[str]) -> Iterable[ModelWithIterations]
```

List available models with filtering.

**Arguments**:

* `order_by` - Field to order results by
* `order_asc` - True for ascending order, False for descending
* `query` - Optional search query to filter results

**Returns**:

* `Iterable[ModelWithIterations]` - Iterator of models matching the specified criteria

#### delete\_model

```python theme={"dark"}
def delete_model(*, model_uuid: UUID) -> None
```

Delete a model.

**Arguments**:

* `model_uuid` - UUID of the model to delete

#### update\_model

```python theme={"dark"}
def update_model(*, model_uuid: UUID, title: Optional[str],
                 description: Optional[str]) -> ModelWithIterations
```

Update a model's metadata.

**Arguments**:

* `model_uuid` - UUID of the model to update
* `title` - New title for the model
* `description` - New description for the model

**Returns**:

* `ModelWithIterations` - Updated model information

#### create\_training\_job

```python theme={"dark"}
def create_training_job(
        *, model_uuid: UUID, batch_size: int, epochs: int,
        features_mapping: Dict[UUID, Dict[str, List[str]]],
        labels_uuids: List[UUID], pretrained_training_uuid: Optional[UUID],
        pretrained_weights_type: Optional[ModelPretrainedWeightsType]) -> UUID
```

Create a new training job for a model.

**Arguments**:

* `model_uuid` - UUID of the model to train
* `batch_size` - Training batch size
* `epochs` - Number of training epochs
* `features_mapping` - Maps project UUIDs to mappings between ontology features and model features.
  This complex structure allows training examples for model features to be sourced from multiple
  projects with different ontologies. For example:

  ```json theme={"dark"}
  {
      project_uuid_0: {
          "ontology_0_feature_0": ["model_feature_0"],
          "ontology_0_feature_1": ["model_feature_1"]
      },
      project_uuid_1: {
          "ontology_1_feature_0": ["model_feature_0", "model_feature_1"]
      }
  }
  ```

  In this case:

  * Training examples for model\_feature\_0 will come from:
  * project\_uuid\_0's ontology\_0\_feature\_0
  * project\_uuid\_1's ontology\_1\_feature\_0
  * Training examples for model\_feature\_1 will come from:
  * project\_uuid\_0's ontology\_0\_feature\_1
  * project\_uuid\_1's ontology\_1\_feature\_0

  The project-level mapping is essential because:

  1. Different projects can use different ontologies
  2. The same semantic concept (e.g. "car") might have different feature IDs across ontologies
  3. Allows flexibly combining training data from multiple sources while maintaining correct
     mappings between ontology features and model features
* `labels_uuids` - List of label UUIDs to use for training
* `pretrained_training_uuid` - Optional UUID of previous training to use for transfer learning
* `pretrained_weights_type` - Optional type of pretrained weights to use

**Returns**:

* `UUID` - The unique identifier of the created training job

#### get\_training\_status

```python theme={"dark"}
def get_training_status(
        *,
        model_uuid: UUID,
        training_uuid: UUID,
        timeout_seconds: int = 7 * 24 * 60 * 60) -> ModelIteration
```

Get the status of a training job.

**Arguments**:

* `model_uuid` - UUID of the model being trained
* `training_uuid` - UUID of the training job
* `timeout_seconds` - Maximum time to wait for training completion. Defaults to 7 days.

**Returns**:

* `ModelIteration` - Information about the training iteration

**Raises**:

* `EncordException` - If training encountered an error
* `ValueError` - If status response is invalid
* `RequestException` - If there are network connectivity issues

#### get\_training\_data

```python theme={"dark"}
def get_training_data(
        *, model_uuid: UUID,
        training_uuid: UUID) -> Iterable[ModelIterationTrainingData]
```

Get information about data used in a training iteration.

**Arguments**:

* `model_uuid` - UUID of the model
* `training_uuid` - UUID of the training iteration

**Returns**:

* `Iterable[ModelIterationTrainingData]` - Iterator of training data items

#### get\_weights\_download\_link

```python theme={"dark"}
def get_weights_download_link(*, model_uuid: UUID, training_uuid: UUID) -> str
```

Get a download link for trained model weights.

**Arguments**:

* `model_uuid` - UUID of the model
* `training_uuid` - UUID of the training iteration

**Returns**:

* `str` - URL for downloading model weights

#### delete\_training\_iteration

```python theme={"dark"}
def delete_training_iteration(*, model_uuid: UUID,
                              training_uuid: UUID) -> None
```

Delete a training iteration.

**Arguments**:

* `model_uuid` - UUID of the model
* `training_uuid` - UUID of the training iteration to delete

#### create\_model\_attachment

```python theme={"dark"}
def create_model_attachment(
        *, project_uuid: UUID, features_mapping: Dict[str, str],
        iteration_policy: ModelIterationPolicy, model_uuid: UUID,
        training_uuids: Optional[List[UUID]]) -> ProjectModelWithIterations
```

Attach a model to a project by mapping the model's features to corresponding ontology features in the project.
This allows a single trained model to be reused across different projects, even if they use different
ontologies to represent the same concepts.

**Arguments**:

* `project_uuid` - UUID of the project to attach the model to
* `features_mapping` - Maps model features to project ontology features. For example:
  ```json theme={"dark"}
  {
      "model_feature_0": "ontology_feature_hash_1",
      "model_feature_1": "ontology_feature_hash_2"
  }
  ```
  This mapping connects each model feature (e.g. "car" detection) to the corresponding
  feature in the project's ontology. Since different projects may use different
  ontologies with different feature hashes for the same concept, this mapping allows
  the same trained model to be reused across projects by correctly mapping its
  features to each project's specific ontology structure.
* `iteration_policy` - Policy for model iteration selection
* `model_uuid` - UUID of the model to attach
* `training_uuids` - Optional list of specific training iterations to use. Only required
  when iteration\_policy is set to MANUAL\_SELECTION.

**Returns**:

* `ProjectModelWithIterations` - Information about the created model attachment

#### list\_model\_attachments

```python theme={"dark"}
def list_model_attachments(
        *, project_uuid: UUID) -> Iterable[ProjectModelWithIterations]
```

List models attached to a project.

**Arguments**:

* `project_uuid` - UUID of the project

**Returns**:

* `Iterable[ProjectModelWithIterations]` - Iterator of attached model information

#### update\_model\_attachment

```python theme={"dark"}
def update_model_attachment(
        *, project_uuid: UUID, project_model_uuid: UUID,
        features_mapping: Dict[str,
                               str], iteration_policy: ModelIterationPolicy,
        training_uuids: Optional[List[UUID]]) -> ProjectModelWithIterations
```

Update how a model is attached to a project by modifying its feature mappings and iteration settings.
This allows you to change how the model's features map to the project's ontology features,
or update which model iterations are used for inference.

**Arguments**:

* `project_uuid` - UUID of the project
* `project_model_uuid` - UUID identifying this specific model attachment to the project
* `features_mapping` - Maps model features to project ontology features. For example:
  ```json theme={"dark"}
  {
      "model_feature_0": "new_ontology_feature_hash_1",
      "model_feature_1": "new_ontology_feature_hash_2"
  }
  ```
  This lets you remap model features to different ontology features - useful
  when the project's ontology has changed or if you want the model to detect
  different classes than it was originally mapped to.
* `iteration_policy` - Updated policy for selecting which trained iteration of the model to use.
  Can be changed between automatically using latest iteration or manually specified ones.
* `training_uuids` - Optional list of specific training iterations to use. Only required
  when iteration\_policy is set to MANUAL\_SELECTION. Allows cherry-picking which
  trained versions of the model to use for inference.

**Returns**:

* `ProjectModelWithIterations` - Information about the updated model attachment

#### delete\_model\_attachment

```python theme={"dark"}
def delete_model_attachment(*, project_uuid: UUID,
                            project_model_uuid: UUID) -> None
```

Remove a model attachment from a project.

**Arguments**:

* `project_uuid` - UUID of the project
* `project_model_uuid` - UUID of the model attachment to project

#### predict\_classification

```python theme={"dark"}
def predict_classification(
    *, project_uuid: UUID, project_model_uuid: UUID, training_uuid: UUID,
    data_uuid: Optional[UUID], data_path: Optional[Path],
    frame_range_from: Optional[int], frame_range_to: Optional[int],
    conf_thresh: float
) -> Dict[int, Optional[PredictionClassificationResultItem]]
```

Run classification prediction on either data\_uuid or data\_path.

**Arguments**:

* `project_uuid` - UUID of the project
* `project_model_uuid` - UUID of the model attachment to project
* `training_uuid` - UUID of the training iteration to use
* `data_uuid` - Optional UUID of data to predict on
* `data_path` - Optional path to local data file
* `frame_range_from` - Optional starting frame for prediction (first frame if not set)
* `frame_range_to` - Optional ending frame for prediction (last frame if not set)
* `conf_thresh` - Confidence threshold for predictions (0.0 - 1.0)

**Returns**:

Dict\[int, Optional\[PredictionClassificationResultItem]]: Dictionary mapping frame numbers to classification results

#### predict\_instance\_segmentation

```python theme={"dark"}
def predict_instance_segmentation(
    *, project_uuid: UUID, project_model_uuid: UUID, training_uuid: UUID,
    data_uuid: Optional[UUID], data_path: Optional[Path],
    frame_range_from: Optional[int], frame_range_to: Optional[int],
    allocation_enabled: bool, conf_thresh: float, iou_thresh: float,
    rdp_thresh: Optional[float]
) -> Dict[int, List[PredictionInstanceSegmentationResultItem]]
```

Run instance segmentation prediction on either data\_uuid or data\_path.

**Arguments**:

* `project_uuid` - UUID of the project
* `project_model_uuid` - UUID of the model attachment to project
* `training_uuid` - UUID of the training iteration to use
* `data_uuid` - Optional UUID of data to predict on
* `data_path` - Optional path to local data file
* `frame_range_from` - Optional starting frame for prediction (first frame if not set)
* `frame_range_to` - Optional ending frame for prediction (last frame if not set)
* `allocation_enabled` - Whether to enable object id tracking
* `conf_thresh` - Confidence threshold for predictions (0.0 - 1.0)
* `iou_thresh` - Intersection over Union threshold (0.0 - 1.0)
* `rdp_thresh` - Optional Ramer-Douglas-Peucker algorithm threshold for polygon simplification

**Returns**:

Dict\[int, List\[PredictionInstanceSegmentationResultItem]]: Dictionary mapping frame numbers to lists of instance segmentation results

#### predict\_object\_detection

```python theme={"dark"}
def predict_object_detection(
        *, project_uuid: UUID, project_model_uuid: UUID, training_uuid: UUID,
        data_uuid: Optional[UUID], data_path: Optional[Path],
        frame_range_from: Optional[int], frame_range_to: Optional[int],
        allocation_enabled: bool, conf_thresh: float, iou_thresh: float
) -> Dict[int, List[PredictionObjectDetectionResultItem]]
```

Run object detection prediction on either data\_uuid or data\_path.

**Arguments**:

* `project_uuid` - UUID of the project
* `project_model_uuid` - UUID of the model attachment to project
* `training_uuid` - UUID of the training iteration to use
* `data_uuid` - Optional UUID of data to predict on
* `data_path` - Optional path to local data file
* `frame_range_from` - Optional starting frame for prediction (first frame if not set)
* `frame_range_to` - Optional ending frame for prediction (last frame if not set)
* `allocation_enabled` - Whether to enable object id tracking
* `conf_thresh` - Confidence threshold for predictions (0.0 - 1.0)
* `iou_thresh` - Intersection over Union threshold (0.0 - 1.0)

**Returns**:

Dict\[int, List\[PredictionObjectDetectionResultItem]]: Dictionary mapping frame numbers to lists of object detection results


# Objects.answers
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.answers



## Answer Objects

```python theme={"dark"}
class Answer(ABC, Generic[ValueType, AttributeType])
```

An internal helper class for the LabelRowV2 class. This class is not meant to be used directly by users.

#### unset

```python theme={"dark"}
def unset() -> None
```

Remove the value from the answer

#### to\_encord\_dict

```python theme={"dark"}
def to_encord_dict(
    ranges: Optional[Ranges] = None,
    space_id: Optional[str] = None
) -> Optional[AttributeDict | DynamicAttributeObject]
```

A low level helper to convert to the Encord JSON format.
For most use cases the `get_answer` function should be used instead.

## TextAnswer Objects

```python theme={"dark"}
class TextAnswer(Answer[str, TextAttribute])
```

#### set

```python theme={"dark"}
def set(value: str,
        manual_annotation: bool = DEFAULT_MANUAL_ANNOTATION) -> None
```

Returns the object itself

## ChecklistAnswer Objects

```python theme={"dark"}
@dataclass
class ChecklistAnswer(Answer[List[FlatOption], ChecklistAttribute])
```

Checkboxes behave slightly different from the other answer types. When the checkbox is unanswered, it will be
the equivalent of not having selected any checkbox answer in the Encord platform.
The initial state will be every checkbox unchecked.


# Objects.attributes
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.attributes



## Attribute Objects

```python theme={"dark"}
class Attribute(OntologyNestedElement, Generic[OptionType])
```

Base class for shared Attribute fields

#### dynamic

The `dynamic` member is part of every attribute. However it can only be true for top level (not nested) attributes
that are part of an [Object](/sdk-documentation/sdk-references/objects.ontology_object#object-objects).

## RadioAttribute Objects

```python theme={"dark"}
class RadioAttribute(Attribute["NestableOption"])
```

An ontology attribute that allows selecting exactly one option
from a list of options.

Each option is represented by a `NestableOption`, which may itself
contain nested attributes (up to 7 levels deep).

#### add\_option

```python theme={"dark"}
def add_option(label: str,
               value: Optional[str] = None,
               local_uid: Optional[int] = None,
               feature_node_hash: Optional[str] = None) -> NestableOption
```

**Arguments**:

* `label` - user-visible name of the option
* `value` - internal unique value; optional; normally mechanically constructed from the label
* `local_uid` - integer identifier of the option. Normally auto-generated;
  omit this unless the aim is to create an exact clone of existing ontology
* `feature_node_hash` - global identifier of the option. Normally auto-generated;
  omit this unless the aim is to create an exact clone of existing ontology

**Returns**:

a `NestableOption` instance attached to the attribute. This can be further specified by adding nested attributes.

## ChecklistAttribute Objects

```python theme={"dark"}
class ChecklistAttribute(Attribute["FlatOption"])
```

An ontology attribute that allows selecting exactly one or more options
from a list of options.

#### add\_option

```python theme={"dark"}
def add_option(label: str,
               value: Optional[str] = None,
               local_uid: Optional[int] = None,
               feature_node_hash: Optional[str] = None) -> FlatOption
```

**Arguments**:

* `label` - user-visible name of the option
* `value` - internal unique value; optional; normally mechanically constructed from the label
* `local_uid` - integer identifier of the option. Normally auto-generated;
  omit this unless the aim is to create an exact clone of existing ontology
* `feature_node_hash` - global identifier of the option. Normally auto-generated;
  omit this unless the aim is to create an exact clone of existing ontology

**Returns**:

a `FlatOption` instance attached to the attribute.

## TextAttribute Objects

```python theme={"dark"}
class TextAttribute(Attribute["FlatOption"])
```

An ontology attribute that allows users to type text strings in a text field.

## NumericAttribute Objects

```python theme={"dark"}
class NumericAttribute(Attribute["FlatOption"])
```

An ontology attribute that allows users to type numerical values (float) in a numerical field.

#### attribute\_from\_dict

```python theme={"dark"}
def attribute_from_dict(d: Dict[str, Any]) -> Attribute
```

Convenience functions as you cannot call static member on union types.


# Objects.bitmask
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.bitmask



## ArrayProtocol Objects

```python theme={"dark"}
@runtime_checkable
class ArrayProtocol(Protocol)
```

Protocol for any object implementing
:ref:`NumPy array interface <https://numpy.org/doc/stable/reference/arrays.interface.html>`

## BitmaskCoordinates Objects

```python theme={"dark"}
class BitmaskCoordinates()
```

#### \_\_init\_\_

```python theme={"dark"}
def __init__(source: Union[ArrayProtocol, BitmaskCoordinates.EncodedBitmask,
                           Dict[str, Any]])
```

Creates a BitmaskCoordinates object from a NumPy array, or other objects that implement
:ref:`NumPy array interface <https://numpy.org/doc/stable/reference/arrays.interface.html>`,
such as Pillow images.

`EncodedBitmask.rle_string` expects an Encord-compatible RLE string. Convert pycocotools/COCO RLE
counts with [coco\_rle\_to\_encord\_rle()](/sdk-documentation/sdk-references/common.bitmask_operations.bitmask_operations#coco_rle_to_encord_rle).

For detailed information please refer to :ref:`bitmask tutorial <tutorials/bitmasks:Bitmasks>`

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: Dict[str, Any]) -> BitmaskCoordinates
```

This method is used to construct object from Encord bitmask dictionary format.
In most cases external users don't need it. Please consider just passing bitmask numpy array compatible object
to the BitmaskCoordinates constructor.

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict[str, Any]
```

This method is used to serialize the object to Encord bitmask dictionary format.
In most cases external users don't need it. Please consider using .to\_numpy\_array method, or just pass this
BitmaskCoordinates objects to a constructor of any class that supports numpy array protocol,
such as NumPy array, Pillow image, etc.

#### to\_numpy\_array

```python theme={"dark"}
def to_numpy_array()
```

Converts the mask to a 2D numpy array with dtype bool.

Numpy needs to be installed for this call to work.


# Objects.classification
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.classification



## OntologyClassificationLevel Objects

```python theme={"dark"}
class OntologyClassificationLevel(StringEnum)
```

Enumeration representing the hierarchical level of a classification
within an ontology.

**Attributes**:

* `GLOBAL` *OntologyClassificationLevel* - Indicates a global, whole-image
  classification that applies to the entire data unit rather than
  to a specific object or region.

## Classification Objects

```python theme={"dark"}
@dataclass
class Classification(OntologyElement)
```

Represents a whole-image classification as part of an Ontology structure.

This class encapsulates an image-level classification that describes the
entire data unit rather than individual labeled objects. Each classification
wraps a single `Attribute` (or multiple, if applicable) that defines metadata
or semantic context for the image, such as scene type, lighting condition,
or general content category.

**Attributes**:

* `uid` *int* - Deprecated. Please use `feature_node_hash` instead.
* `feature_node_hash` *str* - Unique hash value identifying the feature node
  in the ontology tree corresponding to this classification.
* `attributes` *List\[Attribute]* - List of `Attribute` instances that define
  the semantic meaning or properties associated with the classification.
* `_level` *OntologyClassificationLevel | None* - The hierarchical level of
  this classification (for example: `GLOBAL`). Optional: defaults to None.

**Example**:

```
    >>> classification = Classification(
    ...     uid=1,
    ...     feature_node_hash="abc123",
    ...     attributes=[Attribute(name="Scene Type", value="Indoor")],
    ...     level=OntologyClassificationLevel.GLOBAL,
    ... )
```

#### title

```python theme={"dark"}
@property
def title() -> str
```

Returns the title of the classification, which is the name of the first attribute.

**Returns**:

* `str` - The title of the classification.

#### level

```python theme={"dark"}
@property
def level() -> OntologyClassificationLevel | None
```

Get the level of the classification.

**Returns**:

OntologyClassificationLevel | None: The level of the classification.

#### children

```python theme={"dark"}
@property
def children() -> Sequence[OntologyElement]
```

Returns the attributes of the classification as children elements.

**Returns**:

* `Sequence[OntologyElement]` - The attributes of the classification.

#### is\_global

```python theme={"dark"}
@property
def is_global() -> bool
```

Check if the classification is global.

**Returns**:

* `bool` - True if the classification level is global, False otherwise.

#### create\_instance

```python theme={"dark"}
def create_instance(range_only: bool = False) -> ClassificationInstance
```

Create a ClassificationInstance to be used with a label row.

**Returns**:

* `ClassificationInstance` - An instance of ClassificationInstance.

#### from\_dict

```python theme={"dark"}
@classmethod
def from_dict(cls, d: dict) -> Classification
```

Create a Classification instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing classification information.

**Returns**:

* `Classification` - An instance of Classification.

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict[str, Any]
```

Convert the Classification instance to a dictionary.

**Returns**:

Dict\[str, Any]: A dictionary representation of the classification.

**Raises**:

* `ValueError` - If the classification does not have any attributes.

#### add\_attribute

```python theme={"dark"}
def add_attribute(cls: Type[AttributeType],
                  name: str,
                  local_uid: Optional[int] = None,
                  feature_node_hash: Optional[str] = None,
                  required: bool = False) -> AttributeType
```

Adds an attribute to the classification.

**Arguments**:

* `cls` *Type\[AttributeType]* - The attribute type, one of `RadioAttribute`, `ChecklistAttribute`, `TextAttribute`.
* `name` *str* - The user-visible name of the attribute.
* `local_uid` *Optional\[int]* - Integer identifier of the attribute. Normally auto-generated; omit this unless
  the aim is to create an exact clone of an existing ontology.
* `feature_node_hash` *Optional\[str]* - Global identifier of the attribute. Normally auto-generated; omit this
  unless the aim is to create an exact clone of an existing ontology.
* `required` *bool* - Whether the label editor would mark this attribute as 'required'.

**Returns**:

* `AttributeType` - The created attribute that can be further specified with Options, where appropriate.

**Raises**:

* `ValueError` - If the classification already has an attribute assigned.


# Objects.classification expansion
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.classification_expansion



#### expand\_classification\_answers\_into\_frame\_labels

```python theme={"dark"}
def expand_classification_answers_into_frame_labels(
        label: Dict[str, Any]) -> Dict[str, Any]
```

Mutates a label row to expand its `classification_answers` into frame classifications, and
places them onto their spaces/data-units.


# Objects.classification instance
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.classification_instance



## ClassificationInstance Objects

```python theme={"dark"}
class ClassificationInstance()
```

#### classification\_hash

```python theme={"dark"}
@property
def classification_hash() -> str
```

A unique identifier for the classification instance.

#### classification\_name

```python theme={"dark"}
@property
def classification_name() -> str
```

Classification name from the project ontology

#### feature\_hash

```python theme={"dark"}
@property
def feature_hash() -> str
```

Feature node hash from the project ontology

#### created\_by

```python theme={"dark"}
@created_by.setter
def created_by(created_by: Optional[str]) -> None
```

Set the created\_by field with a user email or None if it should default to the current user of the SDK.

#### last\_edited\_by

```python theme={"dark"}
@last_edited_by.setter
def last_edited_by(last_edited_by: Optional[str]) -> None
```

Set the last\_edited\_by field with a user email or None if it should default to the current user of the SDK.

#### set\_for\_frames

```python theme={"dark"}
def set_for_frames(frames: Frames = 0,
                   *,
                   overwrite: bool = False,
                   created_at: Optional[datetime] = None,
                   created_by: Optional[str] = None,
                   confidence: float = DEFAULT_CONFIDENCE,
                   manual_annotation: bool = DEFAULT_MANUAL_ANNOTATION,
                   last_edited_at: Optional[datetime] = None,
                   last_edited_by: Optional[str] = None,
                   reviews: Optional[List[dict]] = None) -> None
```

Places the classification onto the specified frame. If the classification already exists on the frame and
overwrite is set to `True`, the currently specified values will be overwritten.

**Arguments**:

* `frames` - The frame to add the classification instance to. Defaulting to the first frame for convenience.
* `overwrite` - If `True`, overwrite existing data for the given frames. This will not reset all the
  non-specified values. If `False` and data already exists for the given frames,
  raises an error.
* `created_at` - Optionally specify the creation time of the classification instance on this frame. Defaults to `datetime.now()`.
* `created_by` - Optionally specify the creator of the classification instance on this frame. Defaults to the current SDK user.
* `last_edited_at` - Optionally specify the last edit time of the classification instance on this frame. Defaults to `datetime.now()`.
* `last_edited_by` - Optionally specify the last editor of the classification instance on this frame. Defaults to the current SDK
  user.
* `confidence` - Optionally specify the confidence of the classification instance on this frame. Defaults to `1.0`.
* `manual_annotation` - Optionally specify whether the classification instance on this frame was manually annotated. Defaults to `True`.
* `reviews` - Should only be set by internal functions.

#### get\_annotation

```python theme={"dark"}
def get_annotation(frame: Union[int, str] = 0) -> Annotation
```

**Arguments**:

* `frame` - Either the frame number or the image hash if the data type is an image or image group.
  Defaults to the first frame.

#### get\_annotations

```python theme={"dark"}
def get_annotations(
) -> Union[List[Annotation], List[_ClassificationAnnotation]]
```

**Returns**:

A list of `ClassificationInstance.Annotation` in order of available frames.

#### set\_answer

```python theme={"dark"}
def set_answer(answer: Union[str, NumericAnswerValue, Option,
                             Sequence[Option]],
               attribute: Optional[Attribute] = None,
               overwrite: bool = False) -> None
```

Set the answer for a given ontology Attribute. This is the equivalent of e.g. selecting a checkbox in the
UI after adding a ClassificationInstance. There is only one answer per ClassificationInstance per Attribute.

**Arguments**:

* `answer` - The answer to set.
* `attribute` - The ontology attribute to set the answer for. If not set, this will be attempted to be
  inferred.  For answers to [RadioAttribute](/sdk-documentation/sdk-references/objects.attributes#radioattribute-objects) or
  [ChecklistAttribute](/sdk-documentation/sdk-references/objects.attributes#checklistattribute-objects), this can be inferred automatically. For
  [TextAttribute](/sdk-documentation/sdk-references/objects.attributes#textattribute-objects), this will only be inferred if there is only one possible
  TextAttribute to set for the entire classification instance. Otherwise, a
  [LabelRowError](/sdk-documentation/sdk-references/exceptions#labelrowerror-objects) will be thrown.
* `overwrite` - If `True`, the answer will be overwritten if it already exists. If `False`, this will throw
  a LabelRowError if the answer already exists.

#### set\_answer\_from\_list

```python theme={"dark"}
def set_answer_from_list(answers_list: List[AttributeDict]) -> None
```

This is a low level helper function and should not be used directly.

Sets the answer for the classification from a dictionary.

**Arguments**:

* `answers_list` - The list to set the answer from.

#### get\_answer

```python theme={"dark"}
def get_answer(
    attribute: Optional[Attribute] = None
) -> Union[str, Option, Iterable[Option], None]
```

Get the answer set for a given ontology Attribute. Returns `None` if the attribute is not yet answered.

For the ChecklistAttribute, it returns None if and only if
the attribute is nested and the parent is unselected. Otherwise, if not yet answered it will return an empty
list.

**Arguments**:

* `attribute` - The ontology attribute to get the answer for.

#### delete\_answer

```python theme={"dark"}
def delete_answer(attribute: Optional[Attribute] = None) -> None
```

This resets the answer of an attribute as if it was never set.

**Arguments**:

* `attribute` - The ontology attribute to delete the answer for. If not provided, the first level attribute is
  used.

#### copy

```python theme={"dark"}
def copy() -> ClassificationInstance
```

Creates an exact copy of this ClassificationInstance but with a new classification hash and without being
associated to any LabelRowV2. This is useful if you want to add the semantically same
ClassificationInstance to multiple `LabelRowV2`s.

#### get\_all\_static\_answers

```python theme={"dark"}
def get_all_static_answers() -> List[Answer]
```

A low level helper function.

## Annotation Objects

```python theme={"dark"}
class Annotation(_ClassificationAnnotation)
```

Represents an annotation for a specific frame of a ClassficationInstance.
Allows setting or getting data for the ClassificationInstance on the given frame number.
This is deprecated, we will be using the ClassificationAnnotation that this inherits from.

#### reviews

```python theme={"dark"}
@property
def reviews() -> Optional[List[dict]]
```

A read only property about the reviews that happened for this object on this frame.


# Objects.classification ranges
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.classification_ranges



#### resolve\_classification\_ranges

```python theme={"dark"}
def resolve_classification_ranges(
    classification_answer: ClassificationAnswer
) -> tuple[Ranges, dict[str, Ranges]] | None
```

Return the root ranges and child-space ranges represented by a classification answer.

The top-level range is always the root placement. A root entry in `spaces` is unsupported and ignored.


# Objects.common
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.common



## PropertyType Objects

```python theme={"dark"}
class PropertyType(StringEnum)
```

Enumeration of supported classification and attribute types

Values:
radio
text
checklist
numeric

## Shape Objects

```python theme={"dark"}
class Shape(StringEnum)
```

Enumeration of supported geometric and data shapes for labeling.

Values:
bounding\_box
polygon
point
skeleton
polyline
rotatable\_bounding\_box
bitmask
audio
time\_range
text
cuboid
cuboid\_2d
segmentation
circle
ellipse


# Objects.coordinates
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.coordinates



## BoundingBoxCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class BoundingBoxCoordinates()
```

Represents bounding box coordinates, where all values are percentages relative to the total image size.

**Attributes**:

* `height` *float* - The height of the bounding box.
* `width` *float* - The width of the bounding box.
* `top_left_x` *float* - The x-coordinate of the top-left corner.
* `top_left_y` *float* - The y-coordinate of the top-left corner.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: BoundingBoxFrameCoordinatesDict) -> BoundingBoxCoordinates
```

Create a BoundingBoxCoordinates instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing bounding box information.

**Returns**:

* `BoundingBoxCoordinates` - An instance of BoundingBoxCoordinates.

#### to\_dict

```python theme={"dark"}
def to_dict() -> BoundingBoxDict
```

Convert the BoundingBoxCoordinates instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the bounding box coordinates.

## RotatableBoundingBoxCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class RotatableBoundingBoxCoordinates()
```

Represents rotatable bounding box coordinates, where all values are percentages relative to the total image size.

**Attributes**:

* `height` *float* - The height of the bounding box.
* `width` *float* - The width of the bounding box.
* `top_left_x` *float* - The x-coordinate of the top-left corner.
* `top_left_y` *float* - The y-coordinate of the top-left corner.
* `theta` *float* - The angle of rotation originating at the center of the box.

#### theta

angle of rotation originating at center of box

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(
    d: RotatableBoundingBoxFrameCoordinatesDict
) -> RotatableBoundingBoxCoordinates
```

Create a RotatableBoundingBoxCoordinates instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing rotatable bounding box information.

**Returns**:

* `RotatableBoundingBoxCoordinates` - An instance of RotatableBoundingBoxCoordinates.

#### to\_dict

```python theme={"dark"}
def to_dict() -> RotatableBoundingBoxDict
```

Convert the RotatableBoundingBoxCoordinates instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the rotatable bounding box coordinates.

## CircleCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class CircleCoordinates()
```

Represents circle coordinates, where values are normalized relative to image size.

**Attributes**:

* `center_x` *float* - Normalized x-coordinate of the circle center \[0, 1].
* `center_y` *float* - Normalized y-coordinate of the circle center \[0, 1].
* `radius` *float* - Primary semi-axis radius, normalized to image width.
* `stretch` *float* - Ratio of the secondary semi-axis to the primary (1.0 = true circle, !=1.0 = ellipse).
* `theta` *float* - Rotation angle in degrees, clockwise in screen space (matches RBB convention).
  `theta=0` aligns the primary semi-axis (`radius`) with the +X axis.

## EllipseCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class EllipseCoordinates()
```

Represents ellipse coordinates. Mirrors RotatableBoundingBox's
aspect-decoupled normalization: `rx` is normalized to image width,
`ry` to image height, `theta` is a rotation in degrees applied in
screen-pixel space.

**Attributes**:

* `center_x` *float* - Normalized x-coordinate of the ellipse center \[0, 1].
* `center_y` *float* - Normalized y-coordinate of the ellipse center \[0, 1].
* `rx` *float* - Horizontal semi-axis, normalized to image width.
* `ry` *float* - Vertical semi-axis, normalized to image height.
* `theta` *float* - Rotation in degrees, clockwise in screen space.

## CuboidCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class CuboidCoordinates()
```

Represents a cuboid.

**Attributes**:

* `position` *tuple\[float, float, float]* - The (x, y, z) coordinates of the center of the cuboid in the 3D space.
* `orientation` *tuple\[float, float, float]* - The (alpha, beta, gamma) Euler angles of the cuboid, in radians.
* `size` *tuple\[float, float, float]* - The size of the cuboid along its (x, y, z) axes.

## Cuboid2DPerspectiveCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class Cuboid2DPerspectiveCoordinates()
```

Represents a 2.5D prism with perspective projection.

The back face shrinks and moves towards the vanishing point.

**Attributes**:

* `front` *List\[PointCoordinate]* - The vertices of the front face as a list of PointCoordinate objects.
* `vanishing_point` *PointCoordinate* - The point where parallel lines appear to converge.
* `scale_ratio` *float* - The size of the back face relative to the front face (0.0 to N).
  * 2.0: Back face is twice the size.
  * 1.0: No depth (back matches front).
  * 0.5: Back face is half the size.
  * 0.0: Back face recedes infinitely to the vanishing point.

**Examples**:

```python theme={"dark"}
cuboid = Cuboid2DPerspectiveCoordinates(
    front=[PointCoordinate(x=0, y=0), PointCoordinate(x=0.1, y=0),
           PointCoordinate(x=0.1, y=0.1), PointCoordinate(x=0, y=0.1)],
    vanishing_point=PointCoordinate(x=0.4, y=0.3),
    scale_ratio=0.75
)
```

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict
```

Convert the coordinates to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the cuboid 2D coordinates.

## Cuboid2DIsometricCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class Cuboid2DIsometricCoordinates()
```

Represents a 2.5D prism with parallel (isometric) projection.

The back face remains the same size as the front but is shifted by the offset.

**Attributes**:

* `front` *List\[PointCoordinate]* - The vertices of the front face as a list of PointCoordinate objects.
* `offset` *PointCoordinate* - The translation vector  to shift the back face.

**Examples**:

```python theme={"dark"}
cuboid = Cuboid2DIsometricCoordinates(
    front=[PointCoordinate(x=0, y=0), PointCoordinate(x=0.1, y=0),
           PointCoordinate(x=0.1, y=0.1), PointCoordinate(x=0, y=0.1)],
    offset=PointCoordinate(x=0.05, y=-0.05)
)
```

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict
```

Convert the coordinates to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the cuboid 2D coordinates.

#### Cuboid2DCoordinates

Union type for 2D cuboid coordinates - either perspective or isometric projection.

#### cuboid\_2d\_coordinates\_from\_dict

```python theme={"dark"}
def cuboid_2d_coordinates_from_dict(
        d: Cuboid2DFrameCoordinatesDict) -> Cuboid2DCoordinates
```

Create a Cuboid2DCoordinates instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing cuboid\_2d coordinates information.

**Returns**:

* `Cuboid2DCoordinates` - Either Cuboid2DPerspectiveCoordinates or Cuboid2DIsometricCoordinates.

## PointCoordinate Objects

```python theme={"dark"}
@dataclass(frozen=True)
class PointCoordinate()
```

Represents a point coordinate, where all coordinates are a percentage relative to the total image size.

**Attributes**:

* `x` *float* - The x-coordinate of the point.
* `y` *float* - The y-coordinate of the point.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: PointFrameCoordinatesDict) -> PointCoordinate
```

Create a PointCoordinate instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing point coordinate information.

**Returns**:

* `PointCoordinate` - An instance of PointCoordinate.

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict[str, PointDict]
```

Convert the PointCoordinate instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the point coordinate.

## PointCoordinate3D Objects

```python theme={"dark"}
@dataclass(frozen=True)
class PointCoordinate3D()
```

Represents a 3D point coordinate, where all coordinates are a percentage relative to the total image size.

**Attributes**:

* `x` *float* - The x-coordinate of the point.
* `y` *float* - The y-coordinate of the point.
* `z` *float* - The z-coordinate of the point.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: Point3DFrameCoordinatesDict) -> PointCoordinate3D
```

Create a PointCoordinate3D instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing point coordinate information.

**Returns**:

* `PointCoordinate3D` - An instance of PointCoordinate3D.

#### to\_dict

```python theme={"dark"}
def to_dict() -> dict[str, PointDict3D]
```

Convert the PointCoordinate instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the point coordinate.

## PolygonCoordinates Objects

```python theme={"dark"}
class PolygonCoordinates()
```

Represents polygon coordinates

#### \_\_init\_\_

```python theme={"dark"}
def __init__(values: Optional[List[PointCoordinate]] = None,
             polygons: Optional[List[List[List[PointCoordinate]]]] = None)
```

**Arguments**:

* `values` *List\[PointCoordinate]* - A list of PointCoordinate objects defining the polygon.
* `polygons` *List\[List\[List\[PointCoordinate]]]* - A list of polygons, where each polygon is a list of contours, where each contour is a list of points.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: PolygonFrameCoordinatesDict) -> "PolygonCoordinates"
```

Create a PolygonCoordinates instance from a dictionary.

Supports both legacy format (single polygon with one contour) and the new complex format (multiple polygons and contours).

**Arguments**:

* `d` *dict* - Dictionary containing polygon coordinates information.

**Returns**:

* `PolygonCoordinates` - A PolygonCoordinates instance.

**Examples**:

Legacy format (mapping of index -> point):

```json theme={"dark"}
{
  "polygon": {
    "0": {"x": 12.3, "y": 45.6},
    "1": {"x": 78.9, "y": 12.3}
  }
}
```

Legacy format (list of points):

```json theme={"dark"}
{
  "polygon": [
    {"x": 12.3, "y": 45.6},
    {"x": 78.9, "y": 12.3}
  ]
}
```

New format (polygons -> contours -> points):

```json theme={"dark"}
{
  "polygons": [
    [
      [
        {"x": 12.3, "y": 45.6},
        {"x": 78.9, "y": 12.3}
      ]
    ]
  ]
}
```

#### to\_dict

```python theme={"dark"}
def to_dict(
    kind: Union[PolygonCoordsToDict, str] = PolygonCoordsToDict.single_polygon
) -> Union[Dict, List[List[List[float]]]]
```

Convert the PolygonCoordinates instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the polygon coordinates.

## PolylineCoordinates Objects

```python theme={"dark"}
@dataclass(frozen=True)
class PolylineCoordinates()
```

Represents polyline coordinates as a list of point coordinates.

**Attributes**:

* `values` *Union\[List\[PointCoordinate], List\[PointCoordinate3D]]* - A list of (3D) PointCoordinate objects defining the polyline.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(d: PolylineFrameCoordinatesDict) -> PolylineCoordinates
```

Create a PolylineCoordinates instance from a dictionary.

**Arguments**:

* `d` *dict* - A dictionary containing polyline coordinates information.

**Returns**:

* `PolylineCoordinates` - An instance of PolylineCoordinates.

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict
```

Convert the PolylineCoordinates instance to a dictionary.

**Returns**:

* `dict` - A dictionary representation of the polyline coordinates.

## Visibility Objects

```python theme={"dark"}
class Visibility(CamelStrEnum)
```

An enumeration to represent the visibility state of an item.

**Attributes**:

* `VISIBLE` - The item is visible within the frame.
* `INVISIBLE` - The item is outside the frame and thus invisible.
* `OCCLUDED` - The item is within the frame but occluded by something else.
* `SELF_OCCLUDED` - The item is occluded by itself.

## SkeletonCoordinate Objects

```python theme={"dark"}
class SkeletonCoordinate(BaseDTO)
```

Represents a coordinate for a skeleton structure in an image.

**Attributes**:

* `x` *float* - The x-coordinate of the skeleton point.
* `y` *float* - The y-coordinate of the skeleton point.
* `name` *str* - The name of the skeleton point.
* `color` *Optional\[str]* - The color associated with the skeleton point.
* `feature_hash` *Optional\[str]* - A unique hash for the feature.
* `value` *Optional\[str]* - An optional value associated with the skeleton point.
* `visibility` *Optional\[Visibility]* - The visibility state of the skeleton point.

## SkeletonCoordinates Objects

```python theme={"dark"}
class SkeletonCoordinates(BaseDTO)
```

Represents a collection of skeleton coordinates.

**Attributes**:

* `values` *List\[SkeletonCoordinate]* - A list of SkeletonCoordinate objects.
* `name` *str* - The name of the skeleton structure.

#### to\_dict

```python theme={"dark"}
def to_dict(by_alias=True, exclude_none=True) -> Dict[str, Any]
```

Convert the SkeletonCoordinates instance to a dictionary.

**Arguments**:

* `by_alias` *bool* - Whether to use alias for the field names.
* `exclude_none` *bool* - Whether to exclude fields with None values.

**Returns**:

Dict\[str, Any]: A dictionary representation of the skeleton coordinates.

## AudioCoordinates Objects

```python theme={"dark"}
class AudioCoordinates(BaseDTO)
```

Represents coordinates for an audio file

**Attributes**:

* `range` *Ranges* - Ranges in milliseconds for audio files

## TextCoordinates Objects

```python theme={"dark"}
class TextCoordinates(BaseDTO)
```

Represents coordinates for a text file

**Attributes**:

* `range` *Ranges* - Ranges of chars for simple text files

## HtmlCoordinates Objects

```python theme={"dark"}
class HtmlCoordinates(BaseDTO)
```

Represents coordinates for a html file

**Attributes**:

* `range` *List\[HtmlRange]* - A list of HtmlRange objects

#### add\_coordinates\_to\_frame\_object\_dict

```python theme={"dark"}
def add_coordinates_to_frame_object_dict(coordinates: Coordinates,
                                         base_frame_object: BaseFrameObject,
                                         width: Optional[int],
                                         height: Optional[int]) -> FrameObject
```

Attach geometry to a frame object. The wire field and `shape`
discriminator are inferred from the coordinates class.


# Objects.frames
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.frames



## Range Objects

```python theme={"dark"}
@dataclass
class Range()
```

A class representing a range with a start and end value.

**Attributes**:

* `start` *int* - The starting value of the range.
* `end` *int* - The ending value of the range.

#### \_\_slots\_\_

Ranges are used heavily and are simple, so save memory

#### overlaps

```python theme={"dark"}
def overlaps(other) -> bool
```

Check if two ranges overlap

#### merge

```python theme={"dark"}
def merge(other) -> None
```

Merge another range into this one.

#### frame\_to\_range

```python theme={"dark"}
def frame_to_range(frame: int) -> Range
```

Convert a single frame to a Range.

**Arguments**:

* `frame` *int* - The single frame to be converted.

**Returns**:

* `Range` - A Range object with both start and end set to the input frame.

#### frames\_to\_ranges

```python theme={"dark"}
def frames_to_ranges(frames: Collection[int]) -> Ranges
```

Create a sorted list (in ascending order) of non-overlapping run-length encoded ranges from a collection of frames.

**Arguments**:

* `frames` *Collection\[int]* - A collection of integers representing frames.

**Returns**:

* `Ranges` - A list of Range objects representing the non-overlapping ranges.

#### ranges\_to\_list

```python theme={"dark"}
def ranges_to_list(ranges: Ranges) -> List[List[int]]
```

Convert a list of Range objects to a list of lists (run-length encoded) of integers.

**Arguments**:

* `ranges` *Ranges* - A list of Range objects.

**Returns**:

* `List[List[int]]` - A list of lists where each inner list contains two integers, the start and end of a range.

#### range\_to\_ranges

```python theme={"dark"}
def range_to_ranges(range_: Range) -> Ranges
```

Convert a single Range to a list of Ranges.

**Arguments**:

* `range_` *Range* - The single Range to be converted.

**Returns**:

* `Ranges` - A list containing the input Range as its only element.

#### range\_to\_frames

```python theme={"dark"}
def range_to_frames(range_: Range) -> List[int]
```

Convert a single Range (run-length encoded) to a list of integers.

**Arguments**:

* `range_` *Range* - The single Range to be converted.

**Returns**:

* `List[int]` - A list of integers representing the frames within the range.

#### ranges\_to\_frames

```python theme={"dark"}
def ranges_to_frames(range_list: Ranges) -> List[int]
```

Convert a list of Ranges (run-length encoded) to a list of integers.

**Arguments**:

* `range_list` *Ranges* - A list of Range objects.

**Returns**:

* `List[int]` - A sorted list of integers representing all frames within the ranges.

#### ranges\_list\_to\_ranges

```python theme={"dark"}
def ranges_list_to_ranges(range_list: List[List[int]]) -> Ranges
```

Convert a list of lists (run-length encoded) of integers to a list of Range objects.

**Arguments**:

* `range_list` *List\[List\[int]]* - A list of lists where each inner list contains two integers, the start and end of a range.

**Returns**:

* `Ranges` - A list of Range objects created from the input list of lists.

#### frames\_class\_to\_frames\_list

```python theme={"dark"}
def frames_class_to_frames_list(frames_class: Frames) -> List[int]
```

Convert a Frames class (which can be an int, a list of ints, a Range, or a list of Ranges) to a list of integers.

**Arguments**:

* `frames_class` *Frames* - A Frames class which can be a single int, a list of ints, a Range object, or a list of Range objects.

**Returns**:

* `List[int]` - A sorted list of integers representing all frames within the input Frames class.

**Raises**:

* `RuntimeError` - If the input frames\_class is of an unexpected type.


# Objects.html node
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.html_node



## HtmlNode Objects

```python theme={"dark"}
class HtmlNode(BaseDTO)
```

A class representing a single HTML node, with the xpath and offset.

**Attributes**:

* `xpath` *str* - The xpath of the node
* `offset` *int* - The offset of the content from the xpath

## HtmlRange Objects

```python theme={"dark"}
class HtmlRange(BaseDTO)
```

A class representing a section of HTML with a start and end node.

**Attributes**:

* `start` *HtmlNode* - The starting node of the range.
* `end` *HtmlNode* - The ending node of the range.


# Objects.metadata
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.metadata



## DICOMSeriesMetadata Objects

```python theme={"dark"}
class DICOMSeriesMetadata(BaseDTO)
```

Metadata for a DICOM series.

**Attributes**:

* `patient_id` *Optional\[str]* - The ID of the patient. This attribute is optional.
* `study_uid` *str* - The unique identifier for the study.
* `series_uid` *str* - The unique identifier for the series.

## DICOMSliceMetadata Objects

```python theme={"dark"}
class DICOMSliceMetadata(BaseDTO)
```

Metadata for a slice in a DICOM series.

**Attributes**:

* `dicom_instance_uid` *str* - The unique identifier for the DICOM instance.
* `multiframe_frame_number` *Optional\[int]* - The frame number if the DICOM instance is a multiframe image. This attribute is optional.
* `file_uri` *str* - The URI to the file containing the slice.
* `width` *int* - The width of the slice in pixels.
* `height` *int* - The height of the slice in pixels.


# Objects.ontology element
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.ontology_element



## OntologyElement Objects

```python theme={"dark"}
@dataclass
class OntologyElement(ABC)
```

#### children

```python theme={"dark"}
@property
def children() -> Sequence[OntologyElement]
```

Returns an empty sequence of children nodes for this ontology element.
This method is meant to be overridden by subclasses that have actual child nodes.

#### title

```python theme={"dark"}
@property
@abstractmethod
def title() -> str
```

Abstract property that should return the title of the ontology element.
Must be implemented by subclasses.

#### get\_child\_by\_hash

```python theme={"dark"}
def get_child_by_hash(
    feature_node_hash: str,
    type_: Optional[Type[OntologyNestedElementT]] = None
) -> OntologyNestedElementT
```

Retrieves the first child node of this ontology element with the matching feature node hash.
If multiple children have the same hash, the ontology is in an invalid state.
Throws an exception if no matching child is found or if the type does not match.

**Arguments**:

* `feature_node_hash` - The feature node hash of the child node to find.
* `type_` - Optional type to check the type of the child node.

**Returns**:

The child node with the specified feature node hash and type.

#### get\_children\_by\_title

```python theme={"dark"}
def get_children_by_title(
    title: str,
    type_: Optional[Type[OntologyNestedElementT]] = None
) -> List[OntologyNestedElementT]
```

Retrieves all child nodes of this ontology element that match the specified title and type.

**Arguments**:

* `title` - The exact title of the child nodes to find.
* `type_` - Optional type to filter the child nodes.

**Returns**:

A list of child nodes with the specified title and type.

#### get\_child\_by\_title

```python theme={"dark"}
def get_child_by_title(
    title: str,
    type_: Optional[Type[OntologyNestedElementT]] = None
) -> OntologyNestedElementT
```

Retrieves a single child node of this ontology element that matches the specified title and type.
Throws an exception if more than one or no child with the specified title and type is found.

**Arguments**:

* `title` - The exact title of the child node to find.
* `type_` - Optional type to check the type of the child node.

**Returns**:

The child node with the specified title and type.

**Raises**:

* `OntologyError` - If more than one or no matching child is found.

## OntologyNestedElement Objects

```python theme={"dark"}
@dataclass
class OntologyNestedElement(OntologyElement)
```

#### uid

Deprecated. Please use feature\_node\_hash instead.


# Objects.ontology labels impl
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.ontology_labels_impl



## LabelRowV2 Objects

```python theme={"dark"}
class LabelRowV2()
```

This class represents a single label row. It corresponds to exactly one data row within a project and holds all
the labels for that data row.

You can access many metadata fields with this class directly. To read or write labels, you need to call
[initialise\_labels()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#initialise_labels) first. To upload your added labels, call [save()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#save).

#### from\_media\_metadata

```python theme={"dark"}
@classmethod
def from_media_metadata(cls,
                        ontology: Ontology,
                        media_metadata: Union[
                            orm_storage.CustomerProvidedImageMetadata,
                            orm_storage.CustomerProvidedVideoMetadata,
                            orm_storage.CustomerProvidedAudioMetadata,
                            orm_storage.CustomerProvidedTextMetadata,
                            orm_storage.CustomerProvidedPdfMetadata,
                            List[orm_storage.CustomerProvidedImageMetadata],
                        ],
                        *,
                        branch_name: str = "main") -> "LabelRowV2"
```

Create a detached label row from media metadata, without connecting to the Encord platform.

Detached label rows can be used to generate labels programmatically for media files
before they're uploaded. Labels can be serialized via `to_encord_dict()` for later
bulk ingestion.

Server-dependent operations (`save()`, `initialise_labels()`, `workflow_reopen()`,
`workflow_complete()`, etc.) will raise [LabelRowError](/sdk-documentation/sdk-references/exceptions#labelrowerror-objects) on
a detached label row. Use [attach\_to\_project()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#attach_to_project) to connect to a real project.

The serialized dict from `to_encord_dict()` contains placeholder (zero) UUIDs for
identity fields (`label_hash`, `data_hash`, `dataset_hash`). These are replaced
with real server-side values when attached to a project.

**Arguments**:

* `ontology` - The ontology to use for label creation.
* `media_metadata` - Metadata describing the media file. The data type is inferred
  from the metadata class:

  * [CustomerProvidedImageMetadata](/sdk-documentation/sdk-references/orm.storage#customerprovidedimagemetadata-objects) -> IMAGE
  * [CustomerProvidedVideoMetadata](/sdk-documentation/sdk-references/orm.storage#customerprovidedvideometadata-objects) -> VIDEO
  * [CustomerProvidedAudioMetadata](/sdk-documentation/sdk-references/orm.storage#customerprovidedaudiometadata-objects) -> AUDIO
  * [CustomerProvidedTextMetadata](/sdk-documentation/sdk-references/orm.storage#customerprovidedtextmetadata-objects) -> PLAIN\_TEXT
  * [CustomerProvidedPdfMetadata](/sdk-documentation/sdk-references/orm.storage#customerprovidedpdfmetadata-objects) -> PDF
  * `List[CustomerProvidedImageMetadata]` -> IMG\_GROUP
* `branch_name` - Branch name for the label row. Defaults to `"main"`.

**Returns**:

A detached [LabelRowV2](/sdk-documentation/sdk-references/objects.ontology_labels_impl#labelrowv2-objects) instance with labels initialized.

#### label\_hash

```python theme={"dark"}
@property
def label_hash() -> Optional[str]
```

Returns the hash of the label row.

**Returns**:

* `Optional[str]` - The label row hash or None if not set.

#### branch\_name

```python theme={"dark"}
@property
def branch_name() -> str
```

Returns the branch name of the label row.

**Returns**:

* `str` - The branch name.

#### data\_hash

```python theme={"dark"}
@property
def data_hash() -> str
```

Returns the hash of the data row.

**Returns**:

* `str` - The data row hash.

#### group\_hash

```python theme={"dark"}
@property
def group_hash() -> Optional[str]
```

Returns the group hash of the data row.

Only present if this label row is a child of a data group

**Returns**:

* `Optional[str]` - The data group hash.

#### dataset\_hash

```python theme={"dark"}
@property
def dataset_hash() -> str
```

Returns the hash of the dataset.

**Returns**:

* `str` - The dataset hash.

#### dataset\_title

```python theme={"dark"}
@property
def dataset_title() -> str
```

Returns the title of the dataset.

**Returns**:

* `str` - The dataset title.

#### data\_title

```python theme={"dark"}
@property
def data_title() -> str
```

Returns the title of the data row.

**Returns**:

* `str` - The data row title.

#### data\_type

```python theme={"dark"}
@property
def data_type() -> DataType
```

Returns the data type of the label row.

**Returns**:

* `DataType` - The data type.

#### file\_type

```python theme={"dark"}
@property
def file_type() -> Optional[str]
```

Returns the file type of the data row.

**Returns**:

str | None: The file type or None if not set.

#### client\_metadata

```python theme={"dark"}
@property
def client_metadata() -> Optional[dict]
```

Returns the client metadata associated with the label row.

**Returns**:

dict | None: The client metadata or None if not set.

#### label\_status

```python theme={"dark"}
@property
def label_status() -> LabelStatus
```

Returns the current labeling status for the label row.

**Note**: This method is not supported for workflow-based projects. Please see our
:ref:`workflow documentation <tutorials/workflows:Workflows>` for more details.

**Returns**:

* `LabelStatus` - The current labeling status.

**Raises**:

* `WrongProjectTypeError` - If used with workflow-based projects.

#### annotation\_task\_status

```python theme={"dark"}
@property
def annotation_task_status() -> AnnotationTaskStatus
```

Returns the current annotation task status for the label row.

**Note**: This method is not supported for workflow-based projects. Please see our
:ref:`workflow documentation <tutorials/workflows:Workflows>` for more details.

**Returns**:

* `AnnotationTaskStatus` - The current annotation task status.

**Raises**:

* `WrongProjectTypeError` - If used with workflow-based projects.

#### workflow\_graph\_node

```python theme={"dark"}
@property
def workflow_graph_node() -> Optional[WorkflowGraphNode]
```

Returns the workflow graph node associated with the label row.

**Returns**:

* `Optional[WorkflowGraphNode]` - The workflow graph node or None if not set.

#### is\_shadow\_data

```python theme={"dark"}
@property
def is_shadow_data() -> bool
```

Indicates if the label row is shadow data.

**Returns**:

* `bool` - True if the label row is shadow data, False otherwise.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> Optional[datetime]
```

Returns the creation date of the label row.

**Returns**:

* `Optional[datetime]` - The creation date or None if not yet created.

#### last\_edited\_at

```python theme={"dark"}
@property
def last_edited_at() -> Optional[datetime]
```

Returns the last edited date of the label row.

**Returns**:

* `Optional[datetime]` - The last edited date or None if not yet edited.

#### number\_of\_frames

```python theme={"dark"}
@property
def number_of_frames() -> int
```

Returns the number of frames in the label row.

**Returns**:

* `int` - The number of frames.

#### duration

```python theme={"dark"}
@property
def duration() -> Optional[float]
```

Returns the duration of the video data type.

**Returns**:

* `Optional[float]` - The duration or None if not applicable.

#### fps

```python theme={"dark"}
@property
def fps() -> Optional[float]
```

Returns the frames per second (fps) of the video data type.

**Returns**:

* `Optional[float]` - The fps or None if not applicable.

#### data\_link

```python theme={"dark"}
@property
def data_link() -> Optional[str]
```

Returns the data link to the underlying object in either cloud storage or Encord storage. This will be `None`
for DICOM series or image groups created without performance optimizations, as there is no single underlying
file for these data types.

This property will contain a signed URL if [initialise\_labels()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#initialise_labels) was called with `include_signed_url=True`.

**Returns**:

* `Optional[str]` - The data link or None if not applicable.

#### width

```python theme={"dark"}
@property
def width() -> Optional[int]
```

Returns the width of the image data type.

This is `None` for image groups without performance optimization, as there is no single underlying width
for this data type.

**Returns**:

* `Optional[int]` - The width or None if not applicable.

#### height

```python theme={"dark"}
@property
def height() -> Optional[int]
```

Returns the height of the image data type.

This is `None` for image groups without performance optimization, as there is no single underlying height
for this data type.

**Returns**:

* `Optional[int]` - The height or None if not applicable.

#### audio\_codec

```python theme={"dark"}
@property
def audio_codec() -> Optional[str]
```

Returns the codec of the audio data type.

This only applies to audio data types, and returns None for all other data types.

**Returns**:

* `Optional[str]` - The codec or None if not applicable.

#### audio\_sample\_rate

```python theme={"dark"}
@property
def audio_sample_rate() -> Optional[int]
```

Returns the sample rate of the audio data type.

This only applies to audio data types, and returns None for all other data types.

**Returns**:

* `Optional[int]` - The sample rate or None if not applicable.

#### audio\_bit\_depth

```python theme={"dark"}
@property
def audio_bit_depth() -> Optional[int]
```

Returns the bit depth of the audio data type.

This only applies to audio data types, and returns None for all other data types.

**Returns**:

* `Optional[int]` - The bit depth or None if not applicable.

#### audio\_num\_channels

```python theme={"dark"}
@property
def audio_num_channels() -> Optional[int]
```

Returns the number of channels of the audio data type.

This only applies to audio data types, and returns None for all other data types.

**Returns**:

* `Optional[int]` - The number of channels or None if not applicable.

#### backing\_item\_uuid

```python theme={"dark"}
@property
def backing_item_uuid() -> Optional[UUID]
```

Returns the unique identifier (UUID) for the backing storage item associated with this label row.

While it is always included in server responses, it is marked as optional for backward compatibility with earlier versions.

**Returns**:

* `Optional[UUID]` - The backing storage item id or None if not found.

#### task\_uuid

```python theme={"dark"}
@property
def task_uuid() -> Optional[UUID]
```

Returns the workflow task uuids for the task associated with the data unit.

This property only works for workflow-based projects.

**Returns**:

* `Optional[UUID]` - The workflow task uuid or None if not applicable.

**Raises**:

* `WrongProjectTypeError` - If used with non-workflow-based projects.

#### priority

```python theme={"dark"}
@property
def priority() -> Optional[float]
```

Returns the workflow priority for the task associated with the data unit.

This property only works for workflow-based projects.

It is None for label rows in the "complete" state.

**Returns**:

* `Optional[float]` - The workflow priority or None if not applicable.

**Raises**:

* `WrongProjectTypeError` - If used with non-workflow-based projects.

#### is\_valid

```python theme={"dark"}
@property
def is_valid() -> bool
```

Indicates if the labels are valid.

For labels uploaded via the SDK, a check is run to ensure that the labels are valid.
This property returns `True` if the labels have correct structure and match the project ontology.

If it is `False`, then loading the labels via `LabelRowV2` will raise an error, and the label editor
will not be able to load the labels.

You can call [get\_validation\_errors()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#get_validation_errors) to get the validation error messages.

**Returns**:

* `bool` - True if the labels are valid, False otherwise.

#### ontology\_structure

```python theme={"dark"}
@property
def ontology_structure() -> OntologyStructure
```

Get the corresponding ontology structure.

#### is\_labelling\_initialised

```python theme={"dark"}
@property
def is_labelling_initialised() -> bool
```

Check if labelling is initialized.

**Returns**:

* `bool` - `True` if labelling is initialized, `False` otherwise.

  If this is `False`, call the [initialise\_labels()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#initialise_labels) method to read or write specific
  ObjectInstances or ClassificationInstances.

#### is\_detached

```python theme={"dark"}
@property
def is_detached() -> bool
```

Check if this label row is detached (not connected to the Encord platform).

Detached label rows are created via [from\_media\_metadata()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#from_media_metadata) and cannot
perform server operations until attached via [attach\_to\_project()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#attach_to_project).

#### assigned\_user\_email

```python theme={"dark"}
@property
def assigned_user_email() -> Optional[str]
```

Email of the user assigned to annotation or review task for a workflow-based project.
In case of completed task, it is None.

**Returns**:

str | None: The email of the user assigned to the data.

#### last\_actioned\_by\_user\_email

```python theme={"dark"}
@property
def last_actioned_by_user_email() -> Optional[str]
```

Email of the user who last actioned the data.

**Returns**:

str | None: The email of the user who last actioned the data.

#### get\_storage\_item

```python theme={"dark"}
def get_storage_item(get_signed_urls: bool = False) -> StorageItem
```

Returns the storage item associated with the label row.
This function can be used to get storage item details like storage folder, signed url, created at, item type, client metadata, etc.

#### initialise\_storage\_item

```python theme={"dark"}
def initialise_storage_item(get_signed_url: bool = False,
                            bundle: Optional[Bundle] = None) -> None
```

Initialize the storage item associated with the label row.

This function will download the storage item details from the Encord server.
if you want to get the signed url, you can set the get\_signed\_url to True.

**Arguments**:

* `get_signed_url` - If `True`,is set true, you can get the signed url from LabelRowV2.get\_storage\_item().get\_signed\_url()
* `bundle` - If not provided, initialization is performed independently. If provided,
  initialization is delayed and performed along with other objects in the same bundle.

#### initialise\_labels

```python theme={"dark"}
def initialise_labels(include_object_feature_hashes: Optional[Set[str]] = None,
                      include_classification_feature_hashes: Optional[
                          Set[str]] = None,
                      include_reviews: bool = False,
                      include_archived: bool = False,
                      overwrite: bool = False,
                      bundle: Optional[Bundle] = None,
                      *,
                      include_signed_url: bool = False) -> None
```

Initialize labels from the Encord server.

This function downloads or exports labels stored on the Encord server and performs
any other reading or writing operations. If you only want to inspect a subset of labels,
you can filter them. Note that filtering and later uploading will delete all previously
filtered labels.

If the label is not in progress, this sets the label status to `LabelStatus.LABEL_IN_PROGRESS`.

**Arguments**:

* `include_object_feature_hashes` - If `None`, all objects will be included. Otherwise,
  only objects with the specified feature hashes will be included.
* `WARNING` - Use this filter only for reading labels. Saving a filtered subset will
  delete all other object instances stored in the Encord platform.
* `include_classification_feature_hashes` - If `None`, all classifications will be included.
  Otherwise, only classifications with the specified feature hashes will be included.
* `WARNING` - Use this filter only for reading labels. Saving a filtered subset will
  delete all other classification instances stored in the Encord platform.
* `include_reviews` - Whether to request read-only information about the reviews of the label row.
* `include_archived` - Whether to include labels whose ontology features are archived
* `overwrite` - If `True`, overwrite current labels with those stored in the Encord server.
  If `False` and the label row is already initialized, this function will raise an error.
* `bundle` - If not provided, initialization is performed independently. If provided,
  initialization is delayed and performed along with other objects in the same bundle.
* `include_signed_url` - If `True`, the :attr:`.data_link` property will contain a signed URL.
  See documentation for :attr:`.data_link` for more details.

#### from\_labels\_dict

```python theme={"dark"}
def from_labels_dict(label_row_dict: dict,
                     *,
                     preserve_identity: bool = False) -> None
```

Initialize the LabelRow from a label row dictionary.

This function also initializes the label row. It resets all the labels currently
stored within this class.

**Arguments**:

* `label_row_dict` - The dictionary of all labels in the Encord format.
* `preserve_identity` - If True, the current row's identity fields (label\_hash,
  data\_hash, dataset\_hash, branch\_name, and IMG\_GROUP frame hashes) are
  preserved instead of being overwritten from the dict.

#### get\_image\_hash

```python theme={"dark"}
def get_image_hash(frame_number: int) -> Optional[str]
```

Get the corresponding image hash for the frame number.

**Arguments**:

* `frame_number` - The frame number.

**Returns**:

* `Optional[str]` - The image hash if the frame number is within bounds, `None` otherwise.

**Raises**:

* `LabelRowError` - If this function is used for non-image data types.

#### get\_frame\_number

```python theme={"dark"}
def get_frame_number(image_hash: str) -> Optional[int]
```

Get the corresponding frame number for the image hash.

**Arguments**:

* `image_hash` - The image hash.

**Returns**:

* `Optional[int]` - The frame number if the image hash is found, `None` otherwise.

**Raises**:

* `LabelRowError` - If this function is used for non-image data types.

#### get\_spaces

```python theme={"dark"}
def get_spaces() -> list[Space]
```

Retrieves all spaces in the data unit.

Use this to view the available spaces. To work on a specific space, we
recommend using `LabelRowV2.get_space()`.

**Returns**:

A list of all Space objects.

#### get\_space

```python theme={"dark"}
def get_space(*,
              id: Optional[str] = None,
              layout_key: Optional[str] = None,
              type_: SpaceLiteral,
              stream_id: Optional[str] = None,
              event_index: int = 0,
              start_frame: Optional[int] = None,
              file_name: Optional[str] = None) -> Space
```

Retrieves a single space which matches the specified id and type.

Throws an exception if more than one or no space with the specified id and type is found.

**Arguments**:

* `id` - The id of the space to find.
* `layout_key` - The layout key of the data unit within its data group layout.
* `type_` - Type to check the type of the space.
* `stream_id` - For scenes - the name of the stream to find.
* `event_index` - For scenes - the event index within `stream_id`. Defaults to 0.
* `start_frame` - For scene images - the frame where the image event starts.
* `file_name` - The name of the file associated to the space

**Returns**:

The child node with the specified title and type.

**Raises**:

* `OntologyError` - If more than one or no matching child is found.

#### save

```python theme={"dark"}
def save(bundle: Optional[Bundle] = None,
         validate_before_saving: bool = False) -> None
```

Upload the created labels to the Encord server.

This will overwrite any labels that someone else has created on the platform in the meantime.

**Arguments**:

* `bundle` - If not provided, save is executed immediately. If provided, save is executed
  as part of the bundle.
* `validate_before_saving` - Enable stricter server-side integrity checks. Default is `False`.

#### metadata

```python theme={"dark"}
@property
def metadata() -> Optional[Union[DICOMSeriesMetadata, DataGroupMetadata]]
```

Get metadata for the given data type.

**Returns**:

* `Optional[DICOMSeriesMetadata]` - Metadata for the data type, or `None` if not supported.

  Currently only supported for DICOM. Returns `None` for other formats.

  Label row needs to be initialized before using this property.

#### get\_frame\_view

```python theme={"dark"}
def get_frame_view(frame: Union[int, str] = 0) -> FrameView
```

Get a view of the specified frame.

**Arguments**:

* `frame` - Either the frame number or the image hash if the data type is an image or image group.
  Defaults to the first frame.

**Returns**:

* `FrameView` - A view of the specified frame.

#### get\_frame\_metadata

```python theme={"dark"}
def get_frame_metadata(frame: Union[int, str] = 0) -> FrameViewMetadata
```

Get metadata for a specific frame or image hash.

**Arguments**:

* `frame` - The frame number or the image hash. Defaults to the first frame.

**Returns**:

* `FrameViewMetadata` - Metadata for the specified frame or image hash.

**Raises**:

* `LabelRowError` - If the specified frame or image hash is not found in the label row.

#### get\_frames\_metadata

```python theme={"dark"}
def get_frames_metadata() -> List[FrameViewMetadata]
```

Get metadata for all frames in the image group.

**Returns**:

* `List[FrameViewMetadata]` - A list of metadata for each frame.

#### get\_frame\_views

```python theme={"dark"}
def get_frame_views() -> List[FrameView]
```

Get views for all frames.

**Returns**:

* `List[FrameView]` - A list of frame views in order of available frames.

#### get\_object\_instances

```python theme={"dark"}
def get_object_instances(
        filter_ontology_object: Optional[Object] = None,
        filter_frames: Optional[Frames] = None) -> List[ObjectInstance]
```

Get all object instances that match the given filters.

**Arguments**:

* `filter_ontology_object` - Optionally filter by a specific ontology object.
* `filter_frames` - Optionally filter by specific frames.

**Returns**:

* `List[ObjectInstance]` - A list of `ObjectInstance`s that match the filters.

#### add\_object\_instance

```python theme={"dark"}
def add_object_instance(object_instance: ObjectInstance,
                        force: bool = True) -> None
```

Add an object instance to the label row. If the object instance already exists, it overwrites the current instance.

**Arguments**:

* `object_instance` - The object instance to add.
* `force` - If `True`, overwrites the current objects; otherwise, it will replace the current object.

**Raises**:

* `LabelRowError` - If the object instance is already part of another LabelRowV2.

#### add\_classification\_instance

```python theme={"dark"}
def add_classification_instance(
        classification_instance: ClassificationInstance,
        force: bool = False) -> None
```

Add a classification instance to the label row.

**Arguments**:

* `classification_instance` - The classification instance to add.
* `force` - If `True`, overwrites the current objects; otherwise, it will replace the current object.

**Raises**:

* `LabelRowError` - If the classification instance is already part of another LabelRowV2 or has overlapping frames.

#### remove\_classification

```python theme={"dark"}
def remove_classification(classification_instance: ClassificationInstance)
```

Remove a classification instance from a label row.

**Arguments**:

* `classification_instance` - The classification instance to remove.

#### get\_classification\_instances

```python theme={"dark"}
def get_classification_instances(
        filter_ontology_classification: Optional[Classification] = None,
        filter_frames: Optional[Frames] = None
) -> List[ClassificationInstance]
```

Get all classification instances that match the given filters.

**Arguments**:

* `filter_ontology_classification` - Optionally filter by a specific ontology classification.
* `filter_frames` - Optionally filter by specific frames.

**Returns**:

* `List[ClassificationInstance]` - All the `ClassificationInstance`s that match the filter.

#### remove\_object

```python theme={"dark"}
def remove_object(object_instance: ObjectInstance)
```

Remove an object instance from a label row.

**Arguments**:

* `object_instance` - The object instance to remove.

#### to\_encord\_dict

```python theme={"dark"}
def to_encord_dict() -> Dict[str, Any]
```

Convert the label row to a dictionary in Encord format.

This is an internal helper function. Likely this should not be used by a user. To upload labels use the
[save()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#save) function.

**Returns**:

Dict\[str, Any]: A dictionary representing the label row in Encord format.

#### workflow\_reopen

```python theme={"dark"}
def workflow_reopen(bundle: Optional[Bundle] = None) -> None
```

Return a label row to the first annotation stage for re-labeling.

No data will be lost during this call. This method is only relevant for the projects that use the
:ref:`Workflow <tutorials/workflows:Workflows>` feature, and will raise an error for pre-workflow projects.

**Arguments**:

* `bundle` - Optional parameter. If passed, the method will be executed in a deferred way as part of the bundle.

#### workflow\_complete

```python theme={"dark"}
def workflow_complete(bundle: Optional[Bundle] = None) -> None
```

Move a label row to the final workflow node, marking it as 'Complete'.

This method can be called only for labels for which [initialise\_labels()](/sdk-documentation/sdk-references/objects.ontology_labels_impl#initialise_labels) was called at least once, and
consequentially the "label\_hash" field is not `None`. Labels need not be initialized every time the
workflow\_complete() method is called.

This method is only relevant for the projects that use the :ref:`Workflow <tutorials/workflows:Workflows>`
feature, and raises an error for projects that do not use Workflows.

**Arguments**:

* `bundle` - Optional parameter. If passed, the method will be executed in a deferred way as part of the bundle.

**Raises**:

* `LabelRowError` - If the label hash is None.

#### set\_priority

```python theme={"dark"}
def set_priority(priority: float, bundle: Optional[Bundle] = None) -> None
```

Set priority for a task in a workflow project.

**Arguments**:

* `priority` - Float value from 0.0 to 1.0, where 1.0 is the highest priority.
* `bundle` - Optional parameter. If passed, the method will be executed in a deferred way as part of the bundle.

**Raises**:

* `WrongProjectTypeError` - If the project is not a workflow-based project.

#### get\_validation\_errors

```python theme={"dark"}
def get_validation_errors() -> Optional[List[str]]
```

Get validation errors for the label row.

**Returns**:

List\[str] | None: A list of error messages if the label row is invalid, otherwise `None`.

## FrameViewMetadata Objects

```python theme={"dark"}
class FrameViewMetadata()
```

Class to inspect metadata for a frame view.

## FrameView Objects

```python theme={"dark"}
class FrameView()
```

This class can be used to inspect object or classification instances on a given frame,
or metadata such as image file size for a given frame.

#### image\_hash

```python theme={"dark"}
@property
def image_hash() -> str
```

Get the image hash for the current frame.

**Returns**:

* `str` - The image hash.

**Raises**:

* `LabelRowError` - If the data type is not IMAGE or IMG\_GROUP.

#### image\_title

```python theme={"dark"}
@property
def image_title() -> str
```

Get the image title for the current frame.

**Returns**:

* `str` - The image title.

**Raises**:

* `LabelRowError` - If the data type is not IMAGE or IMG\_GROUP.

#### file\_type

```python theme={"dark"}
@property
def file_type() -> str
```

Get the file type for the current frame.

**Returns**:

* `str` - The file type.

**Raises**:

* `LabelRowError` - If the data type is not IMAGE or IMG\_GROUP.

#### frame

```python theme={"dark"}
@property
def frame() -> int
```

Get the frame number.

**Returns**:

* `int` - The frame number.

#### width

```python theme={"dark"}
@property
def width() -> int
```

Get the width of the frame.

**Raises**:

* `LabelRowError` - If the width is not set for the data type.

#### height

```python theme={"dark"}
@property
def height() -> int
```

Get the height of the frame.

**Raises**:

* `LabelRowError` - If the height is not set for the data type.

#### data\_link

```python theme={"dark"}
@property
def data_link() -> Optional[str]
```

Get the data link for the current frame.

**Returns**:

* `Optional[str]` - The data link, or `None` if not available.

**Raises**:

* `LabelRowError` - If the data type is not IMAGE or IMG\_GROUP.

#### metadata

```python theme={"dark"}
@property
def metadata() -> Optional[DICOMSliceMetadata]
```

Get annotation metadata for the current frame.

**Returns**:

* `Optional[DICOMSliceMetadata]` - The metadata for the frame, or `None` if not applicable.

**Notes**:

Currently only supported for DICOM, and will return `None` for other formats.

#### add\_object\_instance

```python theme={"dark"}
def add_object_instance(object_instance: ObjectInstance,
                        coordinates: Coordinates,
                        *,
                        overwrite: bool = False,
                        created_at: Optional[datetime] = None,
                        created_by: Optional[str] = None,
                        last_edited_at: Optional[datetime] = None,
                        last_edited_by: Optional[str] = None,
                        confidence: Optional[float] = None,
                        manual_annotation: Optional[bool] = None) -> None
```

Add an object instance to the current frame.

**Arguments**:

* `object_instance` - The object instance to add.
* `coordinates` - The coordinates for the object instance.
* `overwrite` - Whether to overwrite existing instance data (default is False).
* `created_at` - Optional creation timestamp.
* `created_by` - Optional creator identifier.
* `last_edited_at` - Optional last edited timestamp.
* `last_edited_by` - Optional last editor identifier.
* `confidence` - Optional confidence score.
* `manual_annotation` - Optional flag indicating manual annotation.

**Raises**:

* `LabelRowError` - If the object instance is already assigned to a different label row.

#### add\_classification\_instance

```python theme={"dark"}
def add_classification_instance(
        classification_instance: ClassificationInstance,
        *,
        overwrite: bool = False,
        created_at: Optional[datetime] = None,
        created_by: Optional[str] = None,
        confidence: float = DEFAULT_CONFIDENCE,
        manual_annotation: bool = DEFAULT_MANUAL_ANNOTATION,
        last_edited_at: Optional[datetime] = None,
        last_edited_by: Optional[str] = None) -> None
```

Add a classification instance to the current frame.

**Arguments**:

* `classification_instance` - The classification instance to add.
* `overwrite` - Whether to overwrite existing instance data (default is False).
* `created_at` - Optional creation timestamp.
* `created_by` - Optional creator identifier.
* `confidence` - Confidence score (default is DEFAULT\_CONFIDENCE).
* `manual_annotation` - Flag indicating manual annotation (default is DEFAULT\_MANUAL\_ANNOTATION).
* `last_edited_at` - Optional last edited timestamp.
* `last_edited_by` - Optional last editor identifier.

**Raises**:

* `LabelRowError` - If the classification instance is already assigned to a different label row.

#### get\_object\_instances

```python theme={"dark"}
def get_object_instances(
        filter_ontology_object: Optional[Object] = None
) -> List[ObjectInstance]
```

Get object instances for the current frame.

**Arguments**:

* `filter_ontology_object` - Optionally filter by a specific ontology object.

**Returns**:

* `List[ObjectInstance]` - All `ObjectInstance`s that match the filter.

#### get\_classification\_instances

```python theme={"dark"}
def get_classification_instances(
    filter_ontology_classification: Optional[Classification] = None
) -> List[ClassificationInstance]
```

Get classification instances for the current frame.

**Arguments**:

* `filter_ontology_classification` - Optionally filter by a specific ontology classification.

**Returns**:

* `List[ClassificationInstance]` - All `ClassificationInstance`s that match the filter.

## FrameLevelImageGroupData Objects

```python theme={"dark"}
@dataclass(frozen=True)
class FrameLevelImageGroupData()
```

Data related to a specific frame in an image group.

**Attributes**:

* `image_hash` - Hash of the image.
* `image_title` - Title of the image.
* `file_type` - Type of the file (e.g., JPEG, PNG).
* `frame_number` - The number of the frame in the sequence.
* `width` - Width of the image.
* `height` - Height of the image.
* `data_link` - Optional link to additional data related to the image.

## LabelRowReadOnlyDataImagesDataEntry Objects

```python theme={"dark"}
@dataclass(frozen=True)
class LabelRowReadOnlyDataImagesDataEntry()
```

Read-only data entry for image data in a label row.

**Attributes**:

* `index` - Index of the image.
* `title` - Title of the image.
* `file_type` - Type of the file (e.g., JPEG, PNG).
* `height` - Height of the image.
* `width` - Width of the image.
* `image_hash` - Hash of the image.

## LabelRowReadOnlyData Objects

```python theme={"dark"}
@dataclass(frozen=True)
class LabelRowReadOnlyData()
```

Read-only data for a label row.

**Attributes**:

* `label_hash` - Optional hash for the label. `None` if not initialized for labeling.
* `created_at` - Optional creation timestamp. `None` if not initialized for labeling.
* `last_edited_at` - Optional last edited timestamp. `None` if not initialized for labeling.
* `data_hash` - Hash of the data.
* `data_type` - Type of the data (e.g., IMAGE, VIDEO).
* `label_status` - Status of the label.
* `annotation_task_status` - Optional status of the annotation task.
* `workflow_graph_node` - Optional workflow graph node related to the data.
* `is_shadow_data` - Boolean indicating if the data is shadow data.
* `number_of_frames` - Number of frames in the data.
* `duration` - Optional duration of the video or sequence.
* `fps` - Optional frames per second for video.
* `dataset_hash` - Hash of the dataset.
* `dataset_title` - Title of the dataset.
* `data_title` - Title of the data.
* `audio_codec` - Codec for audio data.
* `audio_bit_depth` - Bit depth for audio data.
* `audio_sample_rate` - Sample Rate for audio data.
* `audio_num_channels` - Number of channels for audio data.
* `width` - Optional width of the data.
* `height` - Optional height of the data.
* `data_link` - Optional link to additional data.
* `task_uuid` - Optional task uuid of the data.
* `priority` - Optional priority of the data.
* `file_type` - Optional file type of the data.
* `client_metadata` - Optional metadata provided by the client.
* `images_data` - Optional list of image data entries.
* `branch_name` - Name of the branch associated with the data.
* `frame_level_data` - Mapping from frame number to frame level data.
* `image_hash_to_frame` - Mapping from image hash to frame number.
* `frame_to_image_hash` - Mapping from frame number to image hash.
* `is_valid` - Boolean indicating if the data is valid.
* `assigned_user_email` - Optional email of the user assigned to the data.
* `last_actioned_by_user_email` - Optional email of the user who last actioned the data.

#### attach\_to\_project

```python theme={"dark"}
def attach_to_project(project: "Project", data_hash: str) -> None
```

Attach a detached label row to a real project data unit.

Fetches the real identity (label\_hash, data\_hash, dataset\_hash, etc.) from the
project and rewrites this row's identity fields. If the server-side label row has
not been initialized yet, it is initialized automatically. After this call, the
label row can be saved to the server via [save()](/sdk-documentation/sdk-references/metadata_schema#save).

.. note::
The ontology used to create this detached label row must match the project's
ontology (same feature hashes). Mismatched feature hashes will cause the server
to reject the save.

Frame counts should be compatible with the server-side data unit. Annotations
on frame numbers beyond the server's frame count may be rejected.

**Arguments**:

* `project` - The Encord project to attach to.
* `data_hash` - The data hash of the target data unit in the project.

**Raises**:

* `LabelRowError` - If no matching label row is found in the project.


# Objects.ontology object
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.ontology_object



## Object Objects

```python theme={"dark"}
@dataclass
class Object(OntologyElement)
```

#### uid

Deprecated. Please use feature\_node\_hash instead.

#### title

```python theme={"dark"}
@property
def title() -> str
```

Returns the name of the object, used as the title.

#### children

```python theme={"dark"}
@property
def children() -> Sequence[OntologyElement]
```

Returns the attributes of the object as its children.

#### create\_instance

```python theme={"dark"}
def create_instance() -> ObjectInstance
```

Create a [ObjectInstance](/sdk-documentation/sdk-references/objects.ontology_object_instance#objectinstance-objects) to be used with a label row.

**Returns**:

* `ObjectInstance` - An instance of the object to be used in labeling.

#### from\_dict

```python theme={"dark"}
@classmethod
def from_dict(cls, d: dict) -> Object
```

Create an Object from a dictionary.

**Arguments**:

* `d` - A dictionary representing the object.

**Returns**:

* `Object` - The created Object instance.

**Raises**:

* `TypeError` - If the shape in the dictionary is not recognized.

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict[str, Any]
```

Convert the Object to a dictionary.

**Returns**:

Dict\[str, Any]: The dictionary representation of the object.

#### add\_attribute

```python theme={"dark"}
def add_attribute(cls: Type[AttributeType],
                  name: str,
                  local_uid: Optional[int] = None,
                  feature_node_hash: Optional[str] = None,
                  required: bool = False,
                  dynamic: bool = False) -> AttributeType
```

Adds an attribute to the object.

**Arguments**:

* `cls` - The attribute type, one of `RadioAttribute`, `ChecklistAttribute`, `TextAttribute`.
* `name` - The user-visible name of the attribute.
* `local_uid` - Integer identifier of the attribute. Normally auto-generated;
  omit this unless the aim is to create an exact clone of an existing ontology.
* `feature_node_hash` - Global identifier of the attribute. Normally auto-generated;
  omit this unless the aim is to create an exact clone of an existing ontology.
* `required` - Whether the label editor would mark this attribute as 'required'.
* `dynamic` - Whether the attribute can have a different answer for the same object across different frames.

**Returns**:

* `AttributeType` - The created attribute that can be further specified with options, where appropriate.

**Raises**:

* `ValueError` - If the specified `local_uid` or `feature_node_hash` violate uniqueness constraints.


# Objects.ontology object instance
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.ontology_object_instance



## ObjectInstance Objects

```python theme={"dark"}
class ObjectInstance()
```

An object instance is an object that has coordinates and can be placed on one or multiple frames in a label row.

#### is\_assigned\_to\_label\_row

```python theme={"dark"}
def is_assigned_to_label_row() -> Optional[LabelRowV2]
```

Checks if the object instance is assigned to a label row.

**Returns**:

The LabelRowV2 instance if assigned, otherwise None.

#### object\_hash

```python theme={"dark"}
@property
def object_hash() -> str
```

A unique identifier for the object instance.

**Returns**:

The unique object hash.

#### ontology\_item

```python theme={"dark"}
@property
def ontology_item() -> Object
```

The ontology object associated with this instance.

**Returns**:

The ontology object.

#### feature\_hash

```python theme={"dark"}
@property
def feature_hash() -> str
```

Feature node hash from the project ontology.

**Returns**:

The feature node hash.

#### object\_name

```python theme={"dark"}
@property
def object_name() -> str
```

Object name from the project ontology.

**Returns**:

The object name.

#### get\_answer

```python theme={"dark"}
def get_answer(
    attribute: Attribute,
    filter_answer: Union[str, NumericAnswerValue, Option, Iterable[Option],
                         None] = None,
    filter_frame: Optional[int] = None,
    is_dynamic: Optional[bool] = None
) -> Union[str, NumericAnswerValue, Option, Iterable[Option], AnswersForFrames,
           None]
```

Get the answer set for a given ontology Attribute. Returns `None` if the attribute is not yet answered.

For the ChecklistAttribute, it returns None if and only if
the attribute is nested and the parent is unselected. Otherwise, if not yet answered it will return an empty
list.

**Arguments**:

* `attribute` - The ontology attribute to get the answer for.
* `filter_answer` - A filter for a specific answer value. Only applies to dynamic attributes.
* `filter_frame` - A filter for a specific frame. Only applies to dynamic attributes.
* `is_dynamic` - Optionally specify whether a dynamic answer is expected or not. This will throw if it is
  set incorrectly according to the attribute. Set this to narrow down the return type.

**Returns**:

If the attribute is static, then the answer value is returned, assuming an answer value has already been
set. If the attribute is dynamic, the AnswersForFrames object is returned.

#### set\_answer

```python theme={"dark"}
def set_answer(answer: Union[str, NumericAnswerValue, Option,
                             Sequence[Option]],
               attribute: Optional[Attribute] = None,
               frames: Optional[Frames] = None,
               overwrite: bool = False,
               manual_annotation: bool = DEFAULT_MANUAL_ANNOTATION) -> None
```

Set the answer for a given ontology Attribute. This is the equivalent of e.g. selecting a checkbox in the
UI after drawing the ObjectInstance. There is only one answer per ObjectInstance per Attribute, unless
the attribute is dynamic (check the args list for more instructions on how to set dynamic answers).

**Arguments**:

* `answer` - The answer to set.
* `attribute` - The ontology attribute to set the answer for. If not set, this will be attempted to be
  inferred.  For answers to [RadioAttribute](/sdk-documentation/sdk-references/objects.attributes#radioattribute-objects) or
  [ChecklistAttribute](/sdk-documentation/sdk-references/objects.attributes#checklistattribute-objects), this can be inferred automatically.
  For [TextAttribute](/sdk-documentation/sdk-references/objects.attributes#textattribute-objects) or [NumericAttribute](/sdk-documentation/sdk-references/objects.attributes#numericattribute-objects),
  this will only be inferred if there is only one possible
  TextAttribute or NumericAttribute to set for the entire object instance.
  Otherwise, a [LabelRowError](/sdk-documentation/sdk-references/exceptions#labelrowerror-objects) will be thrown.
* `frames` - Only relevant for dynamic attributes. The frames to set the answer for. If `None`, the
  answer is set for all frames that this object currently has set coordinates for (also overwriting
  current answers). This will not automatically propagate the answer to new frames that are added in the
  future.
  If this is anything but `None` for non-dynamic attributes, this will
  throw a ValueError.
* `overwrite` - If `True`, the answer will be overwritten if it already exists. If `False`, this will throw
  a LabelRowError if the answer already exists. This argument is ignored for dynamic attributes.
* `manual_annotation` - If `True`, the answer will be marked as manually annotated. This arg defaults to
  DEFAULT\_MANUAL\_ANNOTATION.

#### set\_answer\_from\_list

```python theme={"dark"}
def set_answer_from_list(answers_list: List[AttributeDict]) -> None
```

This is a low level helper function and should usually not be used directly.

Sets the answer for the classification from a dictionary.

**Arguments**:

* `answers_list` - The list of dictionaries to set the answer from.

#### delete\_answer

```python theme={"dark"}
def delete_answer(attribute: Attribute,
                  filter_answer: Optional[Union[str, Option,
                                                Iterable[Option]]] = None,
                  filter_frame: Optional[int] = None) -> None
```

Reset the answer of an attribute as if it was never set.

**Arguments**:

* `attribute` - The attribute to delete the answer for.
* `filter_answer` - A filter for a specific answer value. Delete only answers with the provided value.
  Only applies to dynamic attributes.
* `filter_frame` - A filter for a specific frame. Only applies to dynamic attributes.

#### check\_within\_range

```python theme={"dark"}
def check_within_range(frame: int) -> None
```

Check if the given frame is within the acceptable range.

**Arguments**:

* `frame` - The frame number to check.

**Raises**:

* `LabelRowError` - If the frame is out of the acceptable range.

#### set\_for\_frames

```python theme={"dark"}
def set_for_frames(coordinates: Coordinates,
                   frames: Frames = 0,
                   *,
                   overwrite: bool = False,
                   created_at: Optional[datetime] = None,
                   created_by: Optional[str] = None,
                   last_edited_at: Optional[datetime] = None,
                   last_edited_by: Optional[str] = None,
                   confidence: Optional[float] = None,
                   manual_annotation: Optional[bool] = None,
                   reviews: Optional[List[dict]] = None,
                   is_deleted: Optional[bool] = None) -> None
```

Place the object onto the specified frame(s).

If the object already exists on the frame and overwrite is set to `True`,
the currently specified values will be overwritten.

**Arguments**:

* `coordinates` - The coordinates of the object in the frame.
  This will throw an error if the type of the coordinates does not match the type of the attribute in the object instance.
* `frames` - The frames to add the object instance to. Defaults to the first frame for convenience.
* `overwrite` - If `True`, overwrite existing data for the given frames.
  This will not reset all the non-specified values.
  If `False` and data already exists for the given frames, raises an error.
* `created_at` - Optionally specify the creation time of the object instance on this frame.
  Defaults to `datetime.now()`.
* `created_by` - Optionally specify the creator of the object instance on this frame.
  Defaults to the current SDK user.
* `last_edited_at` - Optionally specify the last edit time of the object instance on this frame.
  Defaults to `datetime.now()`.
* `last_edited_by` - Optionally specify the last editor of the object instance on this frame.
  Defaults to the current SDK user.
* `confidence` - Optionally specify the confidence of the object instance on this frame. Defaults to `1.0`.
* `manual_annotation` - Optionally specify whether the object instance on this frame was manually annotated. Defaults to `True`.
* `reviews` - Should only be set by internal functions.
* `is_deleted` - Should only be set by internal functions.

#### get\_annotation

```python theme={"dark"}
def get_annotation(frame: Union[int, str] = 0) -> Annotation
```

Get the annotation for the object instance on the specified frame.

**Arguments**:

* `frame` - Either the frame number or the image hash if the data type is an image or image group.
  Defaults to the first frame.

**Returns**:

* `Annotation` - The annotation for the specified frame.

**Raises**:

* `LabelRowError` - If the frame is not present in the label row.

#### copy

```python theme={"dark"}
def copy() -> ObjectInstance
```

Create an exact copy of this ObjectInstance.

The new copy will have a new object hash and will not be associated with any `LabelRowV2`.
This is useful for adding the semantically same ObjectInstance to multiple `LabelRowV2`s.

**Returns**:

* `ObjectInstance` - A new ObjectInstance that is a copy of the current instance.

#### get\_annotations

```python theme={"dark"}
def get_annotations() -> List[Annotation]
```

Get all annotations for the object instance on all frames it has been placed on.

**Returns**:

* `List[Annotation]` - A list of `ObjectInstance.Annotation` in order of available frames.

#### get\_annotation\_frames

```python theme={"dark"}
def get_annotation_frames() -> set[int]
```

Get all annotations for the object instance on all frames it has been placed on.

**Returns**:

* `List[Annotation]` - A list of `ObjectInstance.Annotation` in order of available frames.

#### remove\_from\_frames

```python theme={"dark"}
def remove_from_frames(frames: Frames) -> None
```

Remove the object instance from the specified frames.

**Arguments**:

* `frames` - The frames from which to remove the object instance.

#### is\_valid

```python theme={"dark"}
def is_valid() -> None
```

Check if the ObjectInstance is valid.

**Raises**:

* `LabelRowError` - If the ObjectInstance is not on any frames.

#### are\_dynamic\_answers\_valid

```python theme={"dark"}
def are_dynamic_answers_valid() -> None
```

Validate if there are any dynamic answers on frames that have no coordinates.

**Raises**:

* `LabelRowError` - If there are dynamic answers on frames without coordinates.

## Annotation Objects

```python theme={"dark"}
class Annotation(_ObjectAnnotation)
```

Represents an annotation for a specific frame of an ObjectInstance.
Allows setting or getting data for the ObjectInstance on the given frame number.
This is deprecated, we will be using the ObjectAnnotation that this inherits from.

#### is\_deleted

```python theme={"dark"}
@property
def is_deleted() -> Optional[bool]
```

This is merely here for backwards compatibility.

**Returns**:

Optional\[List\[Dict\[str, Any]]]: A list of review dictionaries, if any.

## FrameData Objects

```python theme={"dark"}
@dataclass
class FrameData()
```

Data class for storing frame-specific data.

**Attributes**:

* `coordinates` *Coordinates* - The coordinates associated with the frame.
* `annotation_metadata` \_*AnnotationMetadata* - The frame's metadata information.

#### check\_coordinate\_type

```python theme={"dark"}
def check_coordinate_type(coordinates: Coordinates, ontology_object: Object,
                          parent: Optional[LabelRowV2]) -> None
```

Check if the coordinate type matches the expected type for the ontology object.

**Arguments**:

* `coordinates` *Coordinates* - The coordinates to check.
* `ontology_object` *Object* - The ontology object to check against.
* `parent` *LabelRowV2* - The parent label row (if any) of the ontology object.

**Raises**:

* `LabelRowError` - If the coordinate type does not match the expected type.

## DynamicAnswerManager Objects

```python theme={"dark"}
class DynamicAnswerManager()
```

Manages dynamic answers for different frames of an ObjectInstance.

This class is an internal helper class and should not be interacted with directly by the user.

#### is\_valid\_dynamic\_attribute

```python theme={"dark"}
def is_valid_dynamic_attribute(attribute: Attribute) -> bool
```

Check if the attribute is a valid dynamic attribute.

**Arguments**:

* `attribute` *Attribute* - The attribute to check.

**Returns**:

* `bool` - True if the attribute is valid, False otherwise.

#### delete\_answer

```python theme={"dark"}
def delete_answer(
        attribute: Attribute,
        frames: Optional[Frames] = None,
        filter_answer: Union[str, Option, Iterable[Option],
                             None] = None) -> None
```

Delete the answer for a given attribute and frames.

**Arguments**:

* `attribute` *Attribute* - The attribute to delete the answer for.
* `frames` *Optional\[Frames]* - The frames to delete the answer for.
* `filter_answer` *Union\[str, Option, Iterable\[Option], None]* - The specific answer to delete.

#### set\_answer

```python theme={"dark"}
def set_answer(answer: Union[str, NumericAnswerValue, Option,
                             Iterable[Option]],
               attribute: Attribute,
               frames: Optional[Frames] = None) -> None
```

Set the answer for a given attribute and frames.

**Arguments**:

* `answer` *Union\[str, Option, Iterable\[Option]]* - The answer to set.
* `attribute` *Attribute* - The attribute to set the answer for.
* `frames` *Optional\[Frames]* - The frames to set the answer for.

#### get\_answer

```python theme={"dark"}
def get_answer(attribute: Attribute,
               filter_answer: Union[str, NumericAnswerValue, Option,
                                    Iterable[Option], None] = None,
               filter_frames: Optional[Frames] = None) -> AnswersForFrames
```

Get answers for a given attribute, filtered by the specified criteria.

**Arguments**:

* `attribute` *Attribute* - The attribute to get the answers for.
* `filter_answer` *Union\[str, Option, Iterable\[Option], None]* - The specific answer to filter by.
* `filter_frames` *Optional\[Frames]* - The specific frames to filter by.

**Returns**:

* `AnswersForFrames` - A list of answers and their associated frames.

#### frames

```python theme={"dark"}
def frames() -> Iterable[int]
```

Get all frames that have answers set.

**Returns**:

* `Iterable[int]` - An iterable of frames.

#### get\_all\_answers

```python theme={"dark"}
def get_all_answers() -> List[Tuple[Answer, Ranges]]
```

Get all answers that are set.

**Returns**:

List\[Tuple\[Answer, Ranges]]: A list of tuples containing the answer and its associated ranges.

#### copy

```python theme={"dark"}
def copy() -> DynamicAnswerManager
```

Create a deep copy of the DynamicAnswerManager instance.

**Returns**:

* `DynamicAnswerManager` - A new instance of DynamicAnswerManager with copied data.

## AnswerForFrames Objects

```python theme={"dark"}
@dataclass
class AnswerForFrames()
```

Data class for storing an answer and its associated frame ranges.

**Attributes**:

* `answer` *Union\[str, Option, Iterable\[Option]]* - The answer set for the frames.
* `ranges` *Ranges* - The ranges representing the frames where the answer is set.

  The ranges are essentially a run-length encoding of the frames where the unique answer is set.
  They are sorted in ascending order.

#### AnswersForFrames

A list of AnswerForFrames objects, representing answers and their associated frame ranges.


# Objects.ontology structure
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.ontology_structure



## OntologyStructure Objects

```python theme={"dark"}
@dataclass
class OntologyStructure()
```

#### get\_child\_by\_hash

```python theme={"dark"}
def get_child_by_hash(
        feature_node_hash: str,
        type_: Optional[Type[OntologyElementT]] = None) -> OntologyElementT
```

Returns the first child node of this ontology tree node with the matching feature node hash. If there is
more than one child with the same feature node hash in the ontology tree node, then the ontology would be in
an invalid state. Throws if nothing is found or if the type is not matched.

**Arguments**:

* `feature_node_hash` - The feature\_node\_hash of the child node to search for in the ontology.
* `type_` - The expected type of the item. If the found child does not match the type, an error will be thrown.

**Raises**:

* `OntologyError` - If the item with the specified feature\_node\_hash is not found or if the type does not match.

#### get\_child\_by\_title

```python theme={"dark"}
def get_child_by_title(
        title: str,
        type_: Optional[Type[OntologyElementT]] = None) -> OntologyElementT
```

Returns a child node of this ontology tree node with the matching title and matching type if specified. If more
than one child in this Object have the same title, then an error will be thrown. If no item is found, an error
will be thrown as well.

**Arguments**:

* `title` - The exact title of the child node to search for in the ontology.
* `type_` - The expected type of the child node. Only a node that matches this type will be returned.

**Raises**:

* `OntologyError` - If no child node with the specified title and type is found, or if multiple matches are found.

#### get\_children\_by\_title

```python theme={"dark"}
def get_children_by_title(
        title: str,
        type_: Optional[Type[OntologyElementT]] = None
) -> List[OntologyElementT]
```

Returns all the child nodes of this ontology tree node with the matching title and matching type if specified.
Title in ontologies do not need to be unique, however, we recommend unique titles when creating ontologies.

**Arguments**:

* `title` - The exact title of the child node to search for in the ontology.
* `type_` - The expected type of the item. Only nodes that match this type will be returned.

**Returns**:

* `List[OntologyElementT]` - A list of child nodes with the matching title and type.

#### from\_dict

```python theme={"dark"}
@classmethod
def from_dict(cls, d: Dict[str, Any]) -> OntologyStructure
```

Create an OntologyStructure from a dictionary.

**Arguments**:

* `d` - A JSON blob of an "ontology structure" (e.g. from Encord web app)

**Returns**:

* `OntologyStructure` - The created OntologyStructure object.

**Raises**:

* `KeyError` - If the dict is missing a required field.

#### to\_dict

```python theme={"dark"}
def to_dict() -> Dict[str, List[Dict[str, Any]]]
```

Convert the OntologyStructure to a dictionary.

**Returns**:

Dict\[str, List\[Dict\[str, Any]]]: The dictionary representation of the ontology.

#### add\_object

```python theme={"dark"}
def add_object(name: str,
               shape: Shape,
               uid: Optional[int] = None,
               color: Optional[str] = None,
               feature_node_hash: Optional[str] = None) -> Object
```

Adds an object class definition to the structure.

**Arguments**:

* `name` - The user-visible name of the object.
* `shape` - The kind of object (bounding box, polygon, etc). See :py[Shape](/sdk-documentation/sdk-references/objects.common#shape-objects) enum for possible values.
* `uid` - Integer identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure.
* `color` - The color of the object in the label editor. Normally auto-assigned, should be in '`1A2B3F`' syntax.
* `feature_node_hash` - Global identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure.

**Returns**:

* `Object` - The created object class that can be further customized with attributes.

**Raises**:

* `ValueError` - If a duplicate uid or feature\_node\_hash is provided.

#### add\_classification

```python theme={"dark"}
def add_classification(
        uid: Optional[int] = None,
        feature_node_hash: Optional[str] = None,
        level: Optional[OntologyClassificationLevel] = None) -> Classification
```

Adds a classification definition to the ontology.

**Arguments**:

* `uid` - Integer identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure.
* `feature_node_hash` - Global identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure.
* `level` - The level at which this classification applies. See :py[OntologyClassificationLevel](/sdk-documentation/sdk-references/objects.classification#ontologyclassificationlevel-objects) enum for possible values.

**Returns**:

* `Classification` - The created classification node. Note that classification attribute should be further specified by calling its `add_attribute()` method.

**Raises**:

* `ValueError` - If a duplicate uid or feature\_node\_hash is provided.

#### add\_skeleton\_object

```python theme={"dark"}
def add_skeleton_object(
    name: str,
    skeleton_template: SkeletonTemplate,
    color: Optional[str] = None,
    feature_node_hash: Optional[str] = None
) -> Tuple[Object, SkeletonTemplate]
```

Adds a skeleton object and its template as a linked pair.

The object is minted first and the template reuses the object's `feature_node_hash`.
The two hashes must be equal for the skeleton to render in the label editor, which keys
the object's template option (`skeleton_<objectHash>`) off the template's
`feature_node_hash`. Prefer this over calling `add_object` and `add_skeleton_template`
separately: it removes the need to manage feature hashes by hand.

**Arguments**:

* `name` - The user-visible name of the skeleton object.
* `skeleton_template` - The SkeletonTemplate to link to the object.
* `color` - The color of the object in the label editor. Normally auto-assigned, should be in '`1A2B3F`' syntax.
* `feature_node_hash` - Global identifier shared by the object and its template. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure.

**Returns**:

Tuple\[Object, SkeletonTemplate]: The created skeleton object and its linked template,
sharing one feature\_node\_hash. The template is the same instance that was passed in.

**Raises**:

* `ValueError` - If a duplicate feature\_node\_hash is provided, or a skeleton template
  with the same name already exists. The structure is left unchanged when this is raised.

#### add\_skeleton\_template

```python theme={"dark"}
def add_skeleton_template(skeleton_template: SkeletonTemplate,
                          feature_node_hash: Optional[str] = None) -> None
```

Adds a skeleton template to the ontology structure.

**Arguments**:

* `skeleton_template` - The SkeletonTemplate object to be added.
* `feature_node_hash` - Global identifier of the skeleton template. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure.

**Raises**:

* `ValueError` - If a skeleton template with the same name already exists in the ontology.


# Objects.options
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.options



## Option Objects

```python theme={"dark"}
@dataclass
class Option(OntologyNestedElement)
```

Base class for shared Option fields

## NestableOption Objects

```python theme={"dark"}
@dataclass
class NestableOption(Option)
```

#### add\_nested\_option

```python theme={"dark"}
@deprecated(version="0.1.100", alternative=".add_nested_attribute")
def add_nested_option(cls: Type[AttributeType],
                      name: str,
                      local_uid: Optional[int] = None,
                      feature_node_hash: Optional[str] = None,
                      required: bool = False) -> AttributeType
```

This method is deprecated, please use [add\_nested\_attribute()](/sdk-documentation/sdk-references/objects.options#add_nested_attribute) instead.
There is no functional difference between these methods.

#### add\_nested\_attribute

```python theme={"dark"}
def add_nested_attribute(cls: Type[AttributeType],
                         name: str,
                         local_uid: Optional[int] = None,
                         feature_node_hash: Optional[str] = None,
                         required: bool = False) -> AttributeType
```

Adds a nested attribute to a RadioAttribute option.

**Arguments**:

* `cls` - attribute type, one of `RadioAttribute`, `ChecklistAttribute`, `TextAttribute`
* `name` - the user-visible name of the attribute
* `local_uid` - integer identifier of the attribute. Normally auto-generated;
  omit this unless the aim is to create an exact clone of existing ontology
* `feature_node_hash` - global identifier of the object. Normally auto-generated;
  omit this unless the aim is to create an exact clone of existing ontology
* `required` - whether the label editor would mark this attribute as 'required'

**Returns**:

the created attribute that can be further specified with Options, where appropriate

**Raises**:

* `ValueError` - if specified `local_uid` or `feature_node_hash` violate uniqueness constraints


# Objects.skeleton template
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.skeleton_template



## SkeletonTemplate Objects

```python theme={"dark"}
class SkeletonTemplate(SkeletonTemplateORM)
```

#### required\_vertices

```python theme={"dark"}
@property
def required_vertices() -> Set[str]
```

Get the set of required vertex names for the skeleton.

**Returns**:

* `Set[str]` - A set containing the names of the required vertices.

#### create\_instance

```python theme={"dark"}
def create_instance(
        provided_coordinates: List[SkeletonCoordinate]) -> SkeletonCoordinates
```

Create an instance of SkeletonCoordinates with the provided coordinates.

**Arguments**:

* `provided_coordinates` *List\[SkeletonCoordinate]* - A list of SkeletonCoordinate objects to align.

**Returns**:

* `SkeletonCoordinates` - An instance of SkeletonCoordinates with aligned coordinates.

**Raises**:

* `ValueError` - If the provided vertices do not match the required vertices.


# Objects.spaces.annotation.base annotation
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.annotation.base_annotation



## \_AnnotationMetadata Objects

```python theme={"dark"}
@dataclass
class _AnnotationMetadata()
```

Contains metadata information about an annotation (on a frame or a range)

#### created\_by

None defaults to the user of the SDK once uploaded to the server.

#### last\_edited\_by

None defaults to the user of the SDK once uploaded to the server.

#### from\_dict

```python theme={"dark"}
@staticmethod
def from_dict(
    d: BaseFrameObject | FrameClassification | ClassificationAnswer
) -> "_AnnotationMetadata"
```

Create a AnnotationInfo instance from a dictionary.

**Arguments**:

* `d` - A dictionary containing information about the annotation.

**Returns**:

* `AnnotationInfo` - An instance of AnnotationInfo.

#### update\_from\_optional\_fields

```python theme={"dark"}
def update_from_optional_fields(
        *,
        created_at: Optional[datetime] = None,
        created_by: Optional[str] = None,
        last_edited_at: Optional[datetime] = None,
        last_edited_by: Optional[str] = None,
        confidence: Optional[float] = None,
        manual_annotation: Optional[bool] = None,
        is_deleted: Optional[bool] = None,
        reviews: Optional[List[Dict[Any, Any]]] = None) -> None
```

Update the AnnotationInfo fields with the specified values.

**Arguments**:

* `created_at` - Optional creation time.
* `created_by` - Optional creator identifier.
* `last_edited_at` - Optional last edited time.
* `last_edited_by` - Optional last editor identifier.
* `confidence` - Optional confidence value.
* `manual_annotation` - Optional manual annotation flag.
* `reviews` - Optional list of reviews.
* `is_deleted` - Optional deleted flag.

## \_Annotation Objects

```python theme={"dark"}
class _Annotation(ABC)
```

Class providing common annotation properties.

#### frame

```python theme={"dark"}
@property
@abstractmethod
def frame() -> int
```

int: Gets the frame number.

**Notes**:

This is a legacy attribute. For new subclasses where frame
is not applicable (e.g. audio and text), this returns 0.

#### space

```python theme={"dark"}
@property
@abstractmethod
def space() -> Space
```

Get the space that this annotation is on.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> datetime
```

Get the creation timestamp of the annotation.

#### created\_at

```python theme={"dark"}
@created_at.setter
def created_at(created_at: datetime) -> None
```

Set the creation timestamp of the annotation.

#### created\_by

```python theme={"dark"}
@property
def created_by() -> Optional[str]
```

Get the email of the user who created the annotation.

#### created\_by

```python theme={"dark"}
@created_by.setter
def created_by(created_by: Optional[str]) -> None
```

Set the creator email. None defaults to the current SDK user.

**Arguments**:

* `created_by` - User email or None to default to SDK user.

**Raises**:

* `ValueError` - If the email format is invalid.

#### last\_edited\_at

```python theme={"dark"}
@property
def last_edited_at() -> datetime
```

Get the last edited timestamp of the annotation.

#### last\_edited\_at

```python theme={"dark"}
@last_edited_at.setter
def last_edited_at(last_edited_at: datetime) -> None
```

Set the last edited timestamp of the annotation.

#### last\_edited\_by

```python theme={"dark"}
@property
def last_edited_by() -> Optional[str]
```

Get the email of the user who last edited the annotation.

#### last\_edited\_by

```python theme={"dark"}
@last_edited_by.setter
def last_edited_by(last_edited_by: Optional[str]) -> None
```

Set the last editor email. None defaults to the current SDK user.

**Arguments**:

* `last_edited_by` - User email or None to default to SDK user.

**Raises**:

* `ValueError` - If the email format is invalid.

#### confidence

```python theme={"dark"}
@property
def confidence() -> float
```

Get the confidence score of the annotation.

#### confidence

```python theme={"dark"}
@confidence.setter
def confidence(confidence: float) -> None
```

Set the confidence score of the annotation.

#### manual\_annotation

```python theme={"dark"}
@property
def manual_annotation() -> bool
```

Get whether this annotation was created manually.

#### manual\_annotation

```python theme={"dark"}
@manual_annotation.setter
def manual_annotation(manual_annotation: bool) -> None
```

Set whether this annotation was created manually.

## \_ObjectAnnotation Objects

```python theme={"dark"}
class _ObjectAnnotation(_Annotation)
```

Represents an object annotation on a Space.
Provides access to annotation metadata for a SpaceObject.

#### object\_hash

```python theme={"dark"}
@property
def object_hash() -> str
```

Get the hash of the object instance.

#### coordinates

```python theme={"dark"}
@property
@abstractmethod
def coordinates() -> Coordinates
```

coordinates: Gets the frame number.

**Notes**:

This is a legacy attribute. For new subclasses where coordinates
are not applicable, do not use this attribute. Instead, use `.ranges` instead (e.g. for audio or text spaces)

## \_ClassificationAnnotation Objects

```python theme={"dark"}
class _ClassificationAnnotation(_Annotation)
```

Represents a classification annotation on a Space.
Allows setting or getting annotation data for the Classification.

#### classification\_hash

```python theme={"dark"}
@property
def classification_hash() -> str
```

Get the hash of the object instance.


# Objects.spaces.annotation.html annotation
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.annotation.html_annotation



## \_HtmlObjectAnnotation Objects

```python theme={"dark"}
class _HtmlObjectAnnotation(_ObjectAnnotation)
```

Annotations for HTML modality with XPath-based coordinates.

#### frame

```python theme={"dark"}
@property
def frame() -> int
```

This field is deprecated. It is only here for backwards compatibility. It always returns 0.

#### coordinates

```python theme={"dark"}
@property
def coordinates() -> HtmlCoordinates
```

Get the HTML coordinates for this annotation.

**Returns**:

* `HtmlCoordinates` - The XPath-based coordinates for this annotation.

#### coordinates

```python theme={"dark"}
@coordinates.setter
def coordinates(coordinates: HtmlCoordinates) -> None
```

Set the HTML coordinates for this annotation.

**Arguments**:

* `coordinates` - The new HtmlCoordinates to set.

## \_HtmlClassificationAnnotation Objects

```python theme={"dark"}
class _HtmlClassificationAnnotation(_ClassificationAnnotation)
```

Classification annotations for HTML modality.

#### frame

```python theme={"dark"}
@property
def frame() -> int
```

This field is deprecated. It is only here for backwards compatibility. It always returns 0.


# Objects.spaces.annotation.range annotation
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.annotation.range_annotation



## \_RangeObjectAnnotation Objects

```python theme={"dark"}
class _RangeObjectAnnotation(_ObjectAnnotation)
```

Annotations for range-based modalities (e.g. Text, Audio).

#### frame

```python theme={"dark"}
@property
def frame() -> int
```

This field is deprecated. It is only here for backwards compatibility. It always returns 0.

#### coordinates

```python theme={"dark"}
@coordinates.setter
def coordinates(coordinates: AudioCoordinates | TextCoordinates) -> None
```

This field is deprecated. It is only here for backwards compatibility. Use .ranges instead.


# Objects.spaces.base space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.base_space



## Space Objects

```python theme={"dark"}
class Space(ABC, Generic[ObjectAnnotationT, ClassificationAnnotationT,
                         ClassificationOverlapStrategyT])
```

Manages the objects on a space within LabelRowV2.
Users should not instantiate this class directly, but must obtain these instances via LabelRow\.list\_spaces().

#### get\_object\_instances

```python theme={"dark"}
def get_object_instances() -> list[ObjectInstance]
```

Get all object instances in the space.

**Returns**:

* `list[ObjectInstance]` - List of all object instances present in the space.

#### get\_classification\_instances

```python theme={"dark"}
def get_classification_instances() -> list[ClassificationInstance]
```

Get all classification instances in the space.

**Returns**:

* `list[ClassificationInstance]` - List of all classification instances present in the space.

#### get\_annotations

```python theme={"dark"}
def get_annotations(
    type_: Literal["object", "classification"],
    filter_instance_hashes: Optional[list[str]] = None
) -> Iterator[Union[ObjectAnnotationT, ClassificationAnnotationT,
                    _GlobalClassificationAnnotation]]
```

Get annotations in the space by type.

This method retrieves all annotations of a specified type (object or classification)
within the space. Annotations are returned as an iterator and created lazily as the
iterator is consumed.

**Arguments**:

* `type_` - The type of annotations to retrieve. Must be either:
  * "object": Returns object annotations
  * "classification": Returns classification annotations (including global classifications)
* `filter_instance_hashes` - Optional list of instance hashes to filter by.
  If provided, only annotations matching these hashes will be returned.
  For objects, these should be object hashes; for classifications, classification hashes.

**Returns**:

When type\_ is "object":

* `Iterator[ObjectAnnotationT]` - Iterator over object annotations in the space.
  The concrete annotation type depends on the Space subclass.

  When type\_ is "classification":
  Iterator\[Union\[ClassificationAnnotationT, \_GlobalClassificationAnnotation]]:
  Iterator over classification annotations, including global classifications.


# Objects.spaces.html space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.html_space



## HTMLSpace Objects

```python theme={"dark"}
class HTMLSpace(Space[_HtmlObjectAnnotation, _GlobalClassificationAnnotation,
                      HtmlOverlapStrategy])
```

HTML space implementation for XPath-based annotations.

This space handles annotations on HTML content where positions are
specified using XPath expressions with character offsets.

#### put\_object\_instance

```python theme={"dark"}
def put_object_instance(object_instance: ObjectInstance,
                        ranges: Union[HtmlRange, List[HtmlRange]],
                        *,
                        on_overlap: HtmlOverlapStrategy = "error",
                        created_at: Optional[datetime] = None,
                        created_by: Optional[str] = None,
                        last_edited_at: Optional[datetime] = None,
                        last_edited_by: Optional[str] = None,
                        confidence: Optional[float] = None,
                        manual_annotation: Optional[bool] = None) -> None
```

Add an object instance to the HTML space.

**Arguments**:

* `object_instance` - The object instance to add to the space.
* `ranges` - HtmlRange or list of HtmlRange specifying the XPath-based location(s) for the annotation.
* `on_overlap` - Strategy for handling existing annotations.
  * "error" (default): Raises an error if annotation already exists.
  * "replace": Replaces existing annotation.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If annotation already exists when on\_overlap="error".

#### put\_classification\_instance

```python theme={"dark"}
def put_classification_instance(
        classification_instance: ClassificationInstance,
        *,
        on_overlap: Optional[HtmlOverlapStrategy] = "error",
        created_at: Optional[datetime] = None,
        created_by: Optional[str] = None,
        last_edited_at: Optional[datetime] = None,
        last_edited_by: Optional[str] = None,
        confidence: Optional[float] = None,
        manual_annotation: Optional[bool] = None) -> None
```

Add a classification instance to the HTML space.

**Arguments**:

* `classification_instance` - The classification instance to add to the space.
* `on_overlap` - Strategy for handling existing classifications.
  * "error" (default): Raises an error if classification of the same ontology item already exists.
  * "replace": Overwrites existing classifications.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If classification already exists when on\_overlap="error".

#### remove\_object\_instance

```python theme={"dark"}
def remove_object_instance(object_hash: str) -> Optional[ObjectInstance]
```

Remove an object instance from the HTML space.

**Arguments**:

* `object_hash` - The hash identifier of the object instance to remove.

**Returns**:

* `Optional[ObjectInstance]` - The removed object instance, or None if the object wasn't found.

#### remove\_classification\_instance

```python theme={"dark"}
def remove_classification_instance(
        classification_hash: str) -> Optional[ClassificationInstance]
```

Remove a classification instance from the HTML space.

**Arguments**:

* `classification_hash` - The hash identifier of the classification instance to remove.

**Returns**:

* `Optional[ClassificationInstance]` - The removed classification instance, or None if the classification wasn't found.


# Objects.spaces.image space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.image_space



## ImageSpace Objects

```python theme={"dark"}
class ImageSpace(Space[_GeometricObjectAnnotation,
                       _GlobalClassificationAnnotation, FrameOverlapStrategy])
```

Image space implementation for single-frame image annotations.

#### put\_object\_instance

```python theme={"dark"}
def put_object_instance(object_instance: ObjectInstance,
                        coordinates: Union[GeometricCoordinates, str],
                        *,
                        on_overlap: FrameOverlapStrategy = "error",
                        created_at: Optional[datetime] = None,
                        created_by: Optional[str] = None,
                        last_edited_at: Optional[datetime] = None,
                        last_edited_by: Optional[str] = None,
                        confidence: Optional[float] = None,
                        manual_annotation: Optional[bool] = None) -> None
```

Add an object instance to the image space.

**Arguments**:

* `object_instance` - The object instance to add to the image space.
* `coordinates` - Geometric coordinates for the object (e.g., bounding box, polygon, polyline),
  or an Encord-compatible RLE string for bitmask objects.
  Use `encord.common.bitmask_operations.coco_rle_to_encord_rle` before passing
  pycocotools/COCO RLE counts here.
* `on_overlap` - Strategy for handling existing annotations.
  * "error" (default): Raises an error if annotation already exists.
  * "replace": Overwrites existing annotations.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If annotation already exists when on\_overlap="error".

#### put\_classification\_instance

```python theme={"dark"}
def put_classification_instance(
        classification_instance: ClassificationInstance,
        *,
        on_overlap: Optional[FrameOverlapStrategy] = "error",
        created_at: Optional[datetime] = None,
        created_by: Optional[str] = None,
        last_edited_at: Optional[datetime] = None,
        last_edited_by: Optional[str] = None,
        confidence: Optional[float] = None,
        manual_annotation: Optional[bool] = None) -> None
```

Add a classification instance to the image space.

**Arguments**:

* `classification_instance` - The classification instance to add to the image space.
* `on_overlap` - Strategy for handling existing classifications.
  * "error" (default): Raises an error if classification of the same ontology item already exists.
  * "replace": Overwrites existing classifications.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If classification already exists when on\_overlap="error".

#### remove\_object\_instance

```python theme={"dark"}
def remove_object_instance(object_hash: str) -> Optional[ObjectInstance]
```

Remove an object instance from the image space.

This removes the object and all associated data from the image space.

**Arguments**:

* `object_hash` - The hash identifier of the object instance to remove.

**Returns**:

* `Optional[ObjectInstance]` - The removed object instance, or None if the object wasn't found.

#### remove\_classification\_instance

```python theme={"dark"}
def remove_classification_instance(
        classification_hash: str) -> Optional[ClassificationInstance]
```

Remove a classification instance from the image space.

This removes the classification and all associated data from the image space.

**Arguments**:

* `classification_hash` - The hash identifier of the classification instance to remove.

**Returns**:

* `Optional[ClassificationInstance]` - The removed classification instance, or None if the classification wasn't found.


# Objects.spaces.multiframe space.medical space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.multiframe_space.medical_space



## MedicalSpace Objects

```python theme={"dark"}
class MedicalSpace(MultiFrameSpace)
```

Space for medical files (e.g. DICOM, NIfTI). It handles both medical-file and medical-stack.
Medical-file: Single files with multiple frames.
Medical-stack: Multiple files where frames on each file may have different dimensions.


# Objects.spaces.multiframe space.multiframe space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.multiframe_space.multiframe_space



## MultiFrameSpace Objects

```python theme={"dark"}
class MultiFrameSpace(Space[_GeometricFrameObjectAnnotation,
                            _FrameClassificationAnnotation,
                            FrameOverlapStrategy])
```

Space which handles annotation on multiple frames. E.g. video, dicom, nifti

#### put\_object\_instance

```python theme={"dark"}
def put_object_instance(object_instance: ObjectInstance,
                        frames: Frames,
                        coordinates: Union[GeometricCoordinates, str],
                        *,
                        on_overlap: FrameOverlapStrategy = "error",
                        created_at: Optional[datetime] = None,
                        created_by: Optional[str] = None,
                        last_edited_at: Optional[datetime] = None,
                        last_edited_by: Optional[str] = None,
                        confidence: Optional[float] = None,
                        manual_annotation: Optional[bool] = None) -> None
```

Add an object instance to specific frames in the space.

**Arguments**:

* `object_instance` - The object instance to add to the space.
* `frames` - Frame numbers or ranges where the object should appear. Can be:
  * A single frame number (int)
  * A list of frame numbers (List\[int])
  * A Range object, specifying the start and end of the range (Range)
  * A list of Range objects for multiple ranges (List\[Range])
* `coordinates` - Geometric coordinates for the object (e.g., bounding box, polygon, polyline),
  or an Encord-compatible RLE string for bitmask objects.
  Use `encord.common.bitmask_operations.coco_rle_to_encord_rle` before passing
  pycocotools/COCO RLE counts here.
* `on_overlap` - Strategy for handling existing annotations on the same frames.
  * "error" (default): Raises an error if annotation already exists.
  * "replace": Overwrites existing annotations on overlapping frames.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If frames are invalid or if annotation already exists when on\_overlap="error".

#### set\_dynamic\_answer

```python theme={"dark"}
def set_dynamic_answer(object_instance: ObjectInstance,
                       frames: Frames,
                       answer: Union[str, NumericAnswerValue, Option,
                                     Sequence[Option]],
                       attribute: Optional[Attribute] = None) -> None
```

Set dynamic attribute answers for an object instance on specific frames.

This method is only for dynamic attributes. For static attributes, use `ObjectInstance.set_answer`.

**Arguments**:

* `object_instance` - The object instance to set answers for.
* `frames` - Frame numbers or ranges where the answer should be applied.
* `answer` - The answer value. Can be:
  * str: For text attributes
  * float/int: For numeric attributes
  * Option: For radio attributes
  * Sequence\[Option]: For checklist attributes
* `attribute` - The attribute to set the answer for. If None, will be inferred from the answer type.

**Raises**:

* `LabelRowError` - If the attribute is not dynamic, not a valid child of the object,
  or if the object doesn't exist on the space yet.

#### remove\_dynamic\_answer

```python theme={"dark"}
def remove_dynamic_answer(
    object_instance: ObjectInstance,
    attribute: Attribute,
    frame: int,
    filter_answer: Optional[Union[str, Option,
                                  Iterable[Option]]] = None) -> None
```

Remove a dynamic attribute answer from an object instance on a specific frame.

**Arguments**:

* `object_instance` - The object instance to remove the answer from.
* `attribute` - The dynamic attribute whose answer should be removed.
* `frame` - The frame number to remove the answer from.
* `filter_answer` - Optional filter to remove only specific answer values.
  For checklist attributes, can specify which options to remove.

**Raises**:

* `LabelRowError` - If the attribute is not dynamic or if the object doesn't exist on the space.

#### get\_dynamic\_answer

```python theme={"dark"}
def get_dynamic_answer(
    object_instance: ObjectInstance,
    frames: Frames,
    attribute: Attribute,
    filter_answer: Union[str, NumericAnswerValue, Option, Iterable[Option],
                         None] = None
) -> AnswersForFrames
```

Get dynamic attribute answers for an object instance on specific frames.

This method is only for dynamic attributes. For static attributes, use `ObjectInstance.get_answer`.

**Arguments**:

* `object_instance` - The object instance to get answers from.
* `frames` - Frame numbers or ranges to retrieve answers for.
* `attribute` - The dynamic attribute to get answers for.
* `filter_answer` - Optional filter to retrieve only specific answer values.

**Returns**:

* `AnswersForFrames` - Dictionary mapping frames to their corresponding answers.

**Raises**:

* `LabelRowError` - If the attribute is not dynamic or if the object doesn't exist on the space.

#### put\_classification\_instance

```python theme={"dark"}
def put_classification_instance(
        classification_instance: ClassificationInstance,
        frames: Optional[Frames] = None,
        *,
        on_overlap: Optional[FrameOverlapStrategy] = "error",
        created_at: Optional[datetime] = None,
        created_by: Optional[str] = None,
        last_edited_at: Optional[datetime] = None,
        last_edited_by: Optional[str] = None,
        confidence: Optional[float] = None,
        manual_annotation: Optional[bool] = None) -> None
```

Add a classification instance to specific frames in the video space.

**Arguments**:

* `classification_instance` - The classification instance to add to the space.
* `frames` - Frame numbers or ranges where the classification should appear. Can be:
  * A single frame number (int)
  * A list of frame numbers (List\[int])
  * A Range object, specifying the start and end of the range (Range)
  * A list of Range objects for multiple ranges (List\[Range])
* `on_overlap` - Strategy for handling existing classifications on the same frames.
  * "error" (default): Raises an error if classification already exists.
  * "replace": Overwrites existing classifications on overlapping frames.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If frames are invalid or if classification already exists when on\_overlap="error".

#### remove\_object\_instance

```python theme={"dark"}
def remove_object_instance(
        object_hash: str,
        frames: Optional[Frames] = None) -> Optional[ObjectInstance]
```

Remove an object instance from frames in a space. If no frames are provided, the object instance is removed
from ALL frames in the space.

**Arguments**:

* `object_hash` - The hash identifier of the object instance to remove.
* `frames` - The frames the object instance is to be removed from.

**Returns**:

* `Optional[ObjectInstance]` - The removed object instance, or None if the object wasn't found.

#### remove\_classification\_instance

```python theme={"dark"}
def remove_classification_instance(
        classification_hash: str,
        frames: Optional[Frames] = None) -> Optional[ClassificationInstance]
```

Removes a classification instance from frames in a space. If no frames are passed in, the instance is removed from ALL frames on the space.

This removes the classification from all frames it appears on and cleans up all associated data.

**Arguments**:

* `classification_hash` - The hash identifier of the classification instance to remove.
* `frames` - An optional list of frames to remove the classification instance from.
  If not provided, the classification instance is removed from all frames on this space.

**Returns**:

* `Optional[ClassificationInstance]` - The removed classification instance, or None if the classification wasn't found.


# Objects.spaces.multiframe space.pdf space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.multiframe_space.pdf_space



## PdfSpace Objects

```python theme={"dark"}
class PdfSpace(MultiFrameSpace)
```

PDF space implementation for page-based annotations.

This class provides a page-centric API for PDF annotations, using 'pages' terminology
instead of 'frames' for all public methods.

#### put\_object\_instance

```python theme={"dark"}
def put_object_instance(object_instance: ObjectInstance,
                        pages: Frames,
                        coordinates: GeometricCoordinates,
                        *,
                        on_overlap: FrameOverlapStrategy = "error",
                        created_at: Optional[datetime] = None,
                        created_by: Optional[str] = None,
                        last_edited_at: Optional[datetime] = None,
                        last_edited_by: Optional[str] = None,
                        confidence: Optional[float] = None,
                        manual_annotation: Optional[bool] = None) -> None
```

Add an object instance to specific pages in the PDF.

**Arguments**:

* `object_instance` - The object instance to add to the PDF.
* `pages` - Page numbers or ranges where the object should appear. Can be:
  * A single page number (int)
  * A list of page numbers (List\[int])
  * A Range object, specifying the start and end of the range (Range)
  * A list of Range objects for multiple ranges (List\[Range])
* `coordinates` - Geometric coordinates for the object (e.g., bounding box, polygon, polyline).
* `on_overlap` - Strategy for handling existing annotations on the same pages.
  * "error" (default): Raises an error if annotation already exists.
  * "replace": Overwrites existing annotations on overlapping pages.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If pages are invalid or if annotation already exists when on\_overlap="error".

#### put\_classification\_instance

```python theme={"dark"}
def put_classification_instance(
        classification_instance: ClassificationInstance,
        pages: Optional[Frames] = None,
        *,
        on_overlap: Optional[FrameOverlapStrategy] = "error",
        created_at: Optional[datetime] = None,
        created_by: Optional[str] = None,
        last_edited_at: Optional[datetime] = None,
        last_edited_by: Optional[str] = None,
        confidence: Optional[float] = None,
        manual_annotation: Optional[bool] = None) -> None
```

Add a classification instance to specific pages in the PDF.

**Arguments**:

* `classification_instance` - The classification instance to add to the PDF.
* `pages` - Page numbers or ranges where the classification should appear. Can be:
  * A single page number (int)
  * A list of page numbers (List\[int])
  * A Range object, specifying the start and end of the range (Range)
  * A list of Range objects for multiple ranges (List\[Range])
    For global classifications, set this to None.
* `on_overlap` - Strategy for handling existing classifications on the same pages.
  * "error" (default): Raises an error if classification already exists.
  * "replace": Overwrites existing classifications on overlapping pages.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If pages are invalid or if classification already exists when on\_overlap="error".

#### remove\_object\_instance

```python theme={"dark"}
def remove_object_instance(
        object_hash: str,
        pages: Optional[Frames] = None) -> Optional[ObjectInstance]
```

Remove an object instance from pages on the pdf space. If no pages are provided, the object instance is removed
from ALL pages in the pdf.

**Arguments**:

* `object_hash` - The hash identifier of the object instance to remove.
* `pages` - The pages the object instance is to be removed from.

**Returns**:

* `Optional[ObjectInstance]` - The removed object instance, or None if the object wasn't found.


# Objects.spaces.multiframe space.video space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.multiframe_space.video_space



## VideoSpace Objects

```python theme={"dark"}
class VideoSpace(MultiFrameSpace)
```

Space implementation for frame-based video and image-sequence annotations.

#### \_\_init\_\_

```python theme={"dark"}
def __init__(space_id: str, label_row: LabelRowV2, space_info: SpaceInfo,
             number_of_frames: int, width: int, height: int,
             is_image_sequence: bool)
```

Initialize a video or image-sequence space.

**Arguments**:

* `space_id` - The unique identifier of the space.
* `label_row` - The label row that owns the space.
* `space_info` - The raw space information used to populate the space.
* `number_of_frames` - The total number of frames in the space.
* `width` - The width of each frame in pixels.
* `height` - The height of each frame in pixels.
* `is_image_sequence` - Whether the space represents an image sequence
  rather than a video.


# Objects.spaces.range space.audio space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.range_space.audio_space



## AudioSpace Objects

```python theme={"dark"}
class AudioSpace(RangeSpace)
```

Audio space implementation for range-based annotations.


# Objects.spaces.range space.point cloud space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.range_space.point_cloud_space



## PointCloudFileSpace Objects

```python theme={"dark"}
class PointCloudFileSpace(RangeSpace)
```

#### put\_object\_instance

```python theme={"dark"}
def put_object_instance(object_instance: ObjectInstance,
                        ranges: Ranges | Range | str,
                        *,
                        on_overlap: RangeOverlapStrategy = "error",
                        created_at: Optional[datetime] = None,
                        created_by: Optional[str] = None,
                        last_edited_at: Optional[datetime] = None,
                        last_edited_by: Optional[str] = None,
                        confidence: Optional[float] = None,
                        manual_annotation: Optional[bool] = None) -> None
```

Add an object instance to this point cloud space.

Accepts either explicit `Range` objects or an Encord-compatible RLE string.
When `ranges` is a string it is interpreted as an RLE-encoded set of
point indices and is only valid for segmentation object types.
Use `encord.common.bitmask_operations.coco_rle_to_encord_rle` before passing
pycocotools/COCO RLE counts here.

**Arguments**:

* `object_instance` - The object instance to add to the space.
* `ranges` - Point ranges where the object should appear. Can be:
  * A single `Range` object.
  * A list of `Range` objects.
  * An Encord-compatible RLE string (segmentation shapes only).
* `on_overlap` - Strategy for handling existing annotations on overlapping ranges.
  * "error" (default): Raises an error if annotation already exists.
  * "merge": Adds to new ranges while keeping existing annotations.
  * "replace": Removes existing ranges before adding new ones.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If an RLE string is given for a non-segmentation
  shape, if the RLE string produces no valid ranges, or if ranges overlap
  with existing ones when `on_overlap="error"`.


# Objects.spaces.range space.range space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.range_space.range_space



#### RangeClassificationOverlapStrategy

For now, classifications for range spaces are always global

## RangeSpace Objects

```python theme={"dark"}
class RangeSpace(Space[_RangeObjectAnnotation, _GlobalClassificationAnnotation,
                       RangeClassificationOverlapStrategy])
```

Abstract base class for spaces that manage one dimensional range-based annotations.

This class extracts common logic for managing object and classification instances
across ranges.

#### put\_object\_instance

```python theme={"dark"}
def put_object_instance(object_instance: ObjectInstance,
                        ranges: Ranges | Range,
                        *,
                        on_overlap: RangeOverlapStrategy = "error",
                        created_at: Optional[datetime] = None,
                        created_by: Optional[str] = None,
                        last_edited_at: Optional[datetime] = None,
                        last_edited_by: Optional[str] = None,
                        confidence: Optional[float] = None,
                        manual_annotation: Optional[bool] = None) -> None
```

Add an object instance to specific ranges in the space (audio, text, or HTML).

**Arguments**:

* `object_instance` - The object instance to add to the space.
* `ranges` - Time ranges where the object should appear. Can be:
  * A single Range object (Range)
  * A list of Range objects for multiple ranges (List\[Range])
* `on_overlap` - Strategy for handling existing annotations on overlapping ranges.
  * "error" (default): Raises an error if annotation already exists on overlapping ranges.
  * "merge": Adds the object to new ranges while keeping existing annotations.
  * "replace": Removes object from existing ranges before adding to new ranges.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If ranges are invalid or if annotation already exists when on\_overlap="error".

#### remove\_object\_instance\_from\_range

```python theme={"dark"}
def remove_object_instance_from_range(object_instance: ObjectInstance,
                                      ranges: Ranges | Range) -> Ranges
```

Remove an object instance from specific ranges in the space.

If the object is removed from all ranges, it will be completely removed from the space.

**Arguments**:

* `object_instance` - The object instance to remove from ranges.
* `ranges` - Ranges to remove the object from. Can be:
  * A single Range object (Range)
  * A list of Range objects for multiple ranges (List\[Range])

**Returns**:

* `Ranges` - List of ranges where the object was actually removed.
  Empty if the object didn't exist on any of the specified ranges.

#### put\_classification\_instance

```python theme={"dark"}
def put_classification_instance(
        classification_instance: ClassificationInstance,
        *,
        on_overlap: Optional[RangeClassificationOverlapStrategy] = "error",
        created_at: Optional[datetime] = None,
        created_by: Optional[str] = None,
        last_edited_at: Optional[datetime] = None,
        last_edited_by: Optional[str] = None,
        confidence: Optional[float] = None,
        manual_annotation: Optional[bool] = None) -> None
```

Add a classification instance to the space (audio, text, or HTML).
Currently classification instances exist on the entire space.

**Arguments**:

* `classification_instance` - The classification instance to add to the space.
* `on_overlap` - Strategy for handling existing classifications.
  * "error" (default): Raises an error if classification of the same ontology item already exists.
  * "replace": Overwrites existing classifications.
* `created_at` - Optional timestamp when the annotation was created.
* `created_by` - Optional identifier of who created the annotation.
* `last_edited_at` - Optional timestamp when the annotation was last edited.
* `last_edited_by` - Optional identifier of who last edited the annotation.
* `confidence` - Optional confidence score for the annotation (0.0 to 1.0).
* `manual_annotation` - Optional flag indicating if this was manually annotated.

**Raises**:

* `LabelRowError` - If classification already exists when on\_overlap="error".

#### get\_object\_ranges

```python theme={"dark"}
def get_object_ranges(object_instance: ObjectInstance) -> Ranges
```

Get the ranges for an object instance on this space.

**Arguments**:

* `object_instance` - The object instance to get the ranges for.

**Returns**:

* `Ranges` - The ranges for the object instance on this space.

**Raises**:

* `LabelRowError` - If the object instance is not on this space.

#### remove\_object\_instance

```python theme={"dark"}
def remove_object_instance(object_hash: str) -> Optional[ObjectInstance]
```

Remove an object instance from all ranges in the space.

This completely removes the object and all associated data from the space.

**Arguments**:

* `object_hash` - The hash identifier of the object instance to remove.

**Returns**:

* `Optional[ObjectInstance]` - The removed object instance, or None if the object wasn't found.

#### remove\_classification\_instance

```python theme={"dark"}
def remove_classification_instance(
        classification_hash: str) -> Optional[ClassificationInstance]
```

Remove a classification instance from the space.

This completely removes the classification and all associated data from the space.

**Arguments**:

* `classification_hash` - The hash identifier of the classification instance to remove.

**Returns**:

* `Optional[ClassificationInstance]` - The removed classification instance, or None if the classification wasn't found.


# Objects.spaces.range space.text space
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.range_space.text_space



## TextSpace Objects

```python theme={"dark"}
class TextSpace(RangeSpace)
```

Text space implementation for range-based annotations.


# Objects.spaces.types
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.spaces.types



## RootSpaceMetadata Objects

```python theme={"dark"}
@dataclass(frozen=True)
class RootSpaceMetadata()
```

Metadata for root-level spaces.

## DataGroupMetadata Objects

```python theme={"dark"}
@dataclass(frozen=True)
class DataGroupMetadata()
```

Metadata for spaces originating from a data group.

## SceneMetadata Objects

```python theme={"dark"}
@dataclass(frozen=True)
class SceneMetadata()
```

Metadata for spaces originating from a scene.

#### file\_name

The name of the file, including extension, extracted from the URI.

## BaseSpaceInfo Objects

```python theme={"dark"}
class BaseSpaceInfo(TypedDict)
```

Base information shared by all space info payloads.

## ChildInfo Objects

```python theme={"dark"}
class ChildInfo(TypedDict)
```

Information about a child item within a layout-backed space.

## RootInfo Objects

```python theme={"dark"}
class RootInfo(TypedDict)
```

Information about a root-level file associated with a space.

## VideoSpaceInfo Objects

```python theme={"dark"}
class VideoSpaceInfo(BaseSpaceInfo)
```

Information for a video space.

## ImageSequenceFrameInfo Objects

```python theme={"dark"}
class ImageSequenceFrameInfo(TypedDict)
```

Information about a frame in an image sequence.

## ImageSequenceSpaceInfo Objects

```python theme={"dark"}
class ImageSequenceSpaceInfo(BaseSpaceInfo)
```

Information for an image sequence space.

## ImageSpaceInfo Objects

```python theme={"dark"}
class ImageSpaceInfo(BaseSpaceInfo)
```

Information for an image space.

## TextSpaceInfo Objects

```python theme={"dark"}
class TextSpaceInfo(BaseSpaceInfo)
```

Information for a text space.

## AudioSpaceInfo Objects

```python theme={"dark"}
class AudioSpaceInfo(BaseSpaceInfo)
```

Information for an audio space.

## TimeSeriesSpaceInfo Objects

```python theme={"dark"}
class TimeSeriesSpaceInfo(BaseSpaceInfo)
```

Information for a time series space.

## HtmlSpaceInfo Objects

```python theme={"dark"}
class HtmlSpaceInfo(BaseSpaceInfo)
```

Information for an HTML space.

## MedicalFileSpaceInfo Objects

```python theme={"dark"}
class MedicalFileSpaceInfo(BaseSpaceInfo)
```

Information for a medical file space.

## DicomFrameInfo Objects

```python theme={"dark"}
class DicomFrameInfo(TypedDict)
```

Information about a frame in a DICOM stack.

## MedicalStackSpaceInfo Objects

```python theme={"dark"}
class MedicalStackSpaceInfo(BaseSpaceInfo)
```

Information for a medical stack space.

## FileInSceneInfo Objects

```python theme={"dark"}
class FileInSceneInfo(TypedDict)
```

Information identifying a file within a scene.

## PointCloudFileSpaceInfo Objects

```python theme={"dark"}
class PointCloudFileSpaceInfo(TypedDict)
```

Information for a point cloud file that is part of a scene.

## SceneImageSpaceInfo Objects

```python theme={"dark"}
class SceneImageSpaceInfo(TypedDict)
```

Information for an image file that is part of a scene.

## PdfSpaceInfo Objects

```python theme={"dark"}
class PdfSpaceInfo(BaseSpaceInfo)
```

Information for a PDF space.


# Objects.types
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.types



## CircleDict Objects

```python theme={"dark"}
class CircleDict(TypedDict)
```

#### x

normalized center x \[0, 1]

#### y

normalized center y \[0, 1]

#### r

primary semi-axis radius, normalized to image width

#### stretch

ratio of secondary semi-axis to primary (1.0 = circle, !=1 = ellipse)

#### theta

rotation in degrees, clockwise in screen space (matches RBB convention)

## EllipseDict Objects

```python theme={"dark"}
class EllipseDict(TypedDict)
```

#### x

normalized center x \[0, 1]

#### y

normalized center y \[0, 1]

#### rx

horizontal semi-axis, normalized to image width

#### ry

vertical semi-axis, normalized to image height

#### theta

rotation in degrees, clockwise in screen space

## PointFrameCoordinatesDict Objects

```python theme={"dark"}
class PointFrameCoordinatesDict(TypedDict)
```

#### point

Actually the key here is always '0', but no way to type that.

## Point3DFrameCoordinatesDict Objects

```python theme={"dark"}
class Point3DFrameCoordinatesDict(TypedDict)
```

#### point

Actually the key here is always '0', but no way to type that.

#### PolygonDict

Introduced to support complex polygons

## PolygonFrameCoordinatesDict Objects

```python theme={"dark"}
class PolygonFrameCoordinatesDict(PolygonFrameCoordinatesDictRequired)
```

#### polygons

This was introduced to support complex polygons.

## Cuboid2DPerspectiveDict Objects

```python theme={"dark"}
class Cuboid2DPerspectiveDict(TypedDict)
```

Perspective projection cuboid dict with vanishing point and scale ratio.

#### front

Flat array of coordinates \[x1, y1, x2, y2, ...]

## Cuboid2DIsometricDict Objects

```python theme={"dark"}
class Cuboid2DIsometricDict(TypedDict)
```

Isometric projection cuboid dict with offset.

#### front

Flat array of coordinates \[x1, y1, x2, y2, ...]

#### Cuboid2DDict

Union type for 2D cuboid dict - either perspective or isometric projection.

## AnswerDict Objects

```python theme={"dark"}
class AnswerDict(TypedDict)
```

Answer for attributes/classifications.

## BaseFrameObjectRequired Objects

```python theme={"dark"}
class BaseFrameObjectRequired(TypedDict)
```

Required fields for frame object in label blob.

## BaseFrameObject Objects

```python theme={"dark"}
class BaseFrameObject(BaseFrameObjectRequired)
```

All fields for base frame object in label blob.
Shape data is not included here.

#### createdBy

This is optional because we set the default to the current user on the BE

#### lastEditedBy

This is optional because we set the default to the current user on the BE

#### reviews

TODO: Remove this as its deprecated

#### isDeleted

TODO: Remove this as its deprecated, although its still being sent out

## SegmentationObject Objects

```python theme={"dark"}
class SegmentationObject(BaseFrameObject)
```

#### segmentation

RLE encoded segmentation string

#### FrameObject

Frame object in the label blob. Contains shape data, and is differentiated by the 'shape' field.

## FrameClassification Objects

```python theme={"dark"}
class FrameClassification(FrameClassificationRequired)
```

Frame classification in label blob.
No answers here, they are in the ClassificationAnswer

#### createdBy

This can be optional because we set the default to current the user at the BE

## AttributeDict Objects

```python theme={"dark"}
class AttributeDict(TypedDict)
```

Attribute for a classification OR an object.
Note that these are inappropriately called "classifications" in ObjectAnswer and ClassificationAnswer.

## DynamicAttributeObjectRequired Objects

```python theme={"dark"}
class DynamicAttributeObjectRequired(AttributeDict)
```

Required fields for dynamic attribute object in object\_actions.

## DynamicAttributeObject Objects

```python theme={"dark"}
class DynamicAttributeObject(DynamicAttributeObjectRequired)
```

All fields for dynamic attribute object in object\_actions.

## ClassificationAnswer Objects

```python theme={"dark"}
class ClassificationAnswer(ClassificationAnswerRequired)
```

Classification answer that contains attributes for the classification

#### reviews

TODO: Remove this as its deprecated

## ObjectAnswerForNonGeometric Objects

```python theme={"dark"}
class ObjectAnswerForNonGeometric(BaseFrameObject)
```

For non-geometric modalities, metadata is contained in object answers, instead of frame

#### spaces

Important for non-geometric shapes, where space info must live on ObjectAnswer

## LabelRowDict Objects

```python theme={"dark"}
class LabelRowDict(TypedDict)
```

Work in progress type definition of a label row


# Objects.utils
Source: https://docs.encord.com/sdk-documentation/sdk-references/objects.utils



#### short\_uuid\_str

```python theme={"dark"}
def short_uuid_str() -> str
```

This is being used as a condensed uuid.

#### is\_valid\_email

```python theme={"dark"}
def is_valid_email(email: str) -> bool
```

Validate that an email is a valid one


# Ontology
Source: https://docs.encord.com/sdk-documentation/sdk-references/ontology



## Ontology Ob