❗️

CRITICAL INFORMATION

Ensure you have created a Dataset using cloud data, or local data before continuing.

After the data you want to label is imported into Encord, a few more things have to be prepared before you can start labeling your data:

  1. Create an Ontology. The Ontology is used to label your data and define how concepts are related to each other.

  2. Create a Workflow template. 'Workflows' establish how labeling tasks move through your Project and how they are assigned.

  3. Create a Project. Labels are created and reviewed within Projects. Projects tie together Datasets, Ontologies, and labels.

  4. Add users to your Project. Add annotators, reviewers, annotators & reviewers, project managers, and admins to your Project.

1. Create an Ontology

ℹ️

Note

We recommend using the Encord platform to create Ontologies. The platform allows you to visualize how different elements of the Ontology 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 in step 3.

import logging
import time
from tqdm import tqdm
from encord import EncordUserClient
from encord.objects import Shape, Object, Option
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.objects.attributes import RadioAttribute, ChecklistAttribute

from encord.http.constants import RequestsSettings

requests_settings = RequestsSettings(
    max_retries=10,
    read_timeout=1800,
    write_timeout=1800,
)

# Authenticate user. 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>",
    requests_settings=requests_settings
)

# Create a new ontology with annotations and classifications
ontology = user_client.create_ontology("My test ontology", structure=None)

# Adding an object with name "Cute Cat", with type Bounding Box
cat_object = ontology.structure.add_object("Cute Cat", shape=Shape.BOUNDING_BOX)

# Now let's add some classifications
cat_colour = cat_object.add_attribute(RadioAttribute, "colour", required=True)
cat_colour.add_option("white")
cat_colour.add_option("black")

cat_features = cat_object.add_attribute(ChecklistAttribute, "features")
cat_features.add_option("soft")
cat_features.add_option("fluffy")
cat_features.add_option("friendly")

# And here you are, let's save it
ontology.save()

# Prints the ontology hash
print (ontology.ontology_hash)
import logging
import time
from tqdm import tqdm
from encord import EncordUserClient
from encord.objects import Shape, Object, Option
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.objects.attributes import RadioAttribute, ChecklistAttribute

from encord.http.constants import RequestsSettings

requests_settings = RequestsSettings(
    max_retries=10,
    read_timeout=1800,
    write_timeout=1800,
)

# Authenticate user. 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>",
    requests_settings=requests_settings
)

# Create a new ontology with annotations and classifications
ontology = user_client.create_ontology("My test ontology", structure=None)

# Adding an object with name "Cute Cat", with type Rotatable Bounding Box
cat_object = ontology.structure.add_object("Cute Cat", shape=Shape.ROTATABLE_BOUNDING_BOX)

# Now let's add some classifications
cat_colour = cat_object.add_attribute(RadioAttribute, "colour", required=True)
cat_colour.add_option("white")
cat_colour.add_option("black")

cat_features = cat_object.add_attribute(ChecklistAttribute, "features")
cat_features.add_option("soft")
cat_features.add_option("fluffy")
cat_features.add_option("friendly")

# And here you are, let's save it
ontology.save()

# Prints the ontology hash
print (ontology.ontology_hash)
import logging
import time
from tqdm import tqdm
from encord import EncordUserClient
from encord.objects import Shape, Object, Option
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.objects.attributes import RadioAttribute, ChecklistAttribute

from encord.http.constants import RequestsSettings

requests_settings = RequestsSettings(
    max_retries=10,
    read_timeout=1800,
    write_timeout=1800,
)

# Authenticate user. 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>",
    requests_settings=requests_settings
)

# Create a new ontology with annotations and classifications
ontology = user_client.create_ontology("My test ontology", structure=None)

# Adding an object with name "Cute Cat", with type Polygon
cat_object = ontology.structure.add_object("Cute Cat", shape=Shape.POLYGON)

# Now let's add some classifications
cat_colour = cat_object.add_attribute(RadioAttribute, "colour", required=True)
cat_colour.add_option("white")
cat_colour.add_option("black")

cat_features = cat_object.add_attribute(ChecklistAttribute, "features")
cat_features.add_option("soft")
cat_features.add_option("fluffy")
cat_features.add_option("friendly")

# And here you are, let's save it
ontology.save()

# Prints the ontology hash
print (ontology.ontology_hash)
import logging
import time
from tqdm import tqdm
from encord import EncordUserClient
from encord.objects import Shape, Object, Option
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.objects.attributes import RadioAttribute, ChecklistAttribute

from encord.http.constants import RequestsSettings

requests_settings = RequestsSettings(
    max_retries=10,
    read_timeout=1800,
    write_timeout=1800,
)

# Authenticate user. 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>",
    requests_settings=requests_settings
)

# Create a new ontology with annotations and classifications
ontology = user_client.create_ontology("My test ontology", structure=None)

# Adding an object with name "Cute Cat", with type Bitmask
cat_object = ontology.structure.add_object("Cute Cat", shape=Shape.BITMASK)

# Now let's add some classifications
cat_colour = cat_object.add_attribute(RadioAttribute, "colour", required=True)
cat_colour.add_option("white")
cat_colour.add_option("black")

cat_features = cat_object.add_attribute(ChecklistAttribute, "features")
cat_features.add_option("soft")
cat_features.add_option("fluffy")
cat_features.add_option("friendly")

# And here you are, let's save it
ontology.save()

# Prints the ontology hash
print (ontology.ontology_hash)

2. Create a Workflow template

Workflow templates must be created using the Encord platform. See our documentation to learn more.

The Workflow template ID / template hash is used to reference the template in Step 3.

3. Create a Project

Once you have your data, your Ontology, and a Workflow template, it is time to create a Project.

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. See here for more information.
  • <ontology_hash> with the hash of the Ontology you created for this Project (output in Step 1). See here for more information.
  • <template_hash> with the hash of the Workflow template. See here for more information.

👍

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.

# 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)
a8b8d026-1c99-4cfc-910d-7f66be957f3d

4. Add users to your Project

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 in Step 3.
# 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(
    ["[email protected]", "[email protected]"],
    user_role=ProjectUserRole.ANNOTATOR,
)

# Add two reviewers to the Project
project.add_users(
    ["[email protected]", "[email protected]"],
    user_role=ProjectUserRole.REVIEWER,
)

# Add one Team Manager to the Project
project.add_users(
    ["[email protected]"],
    user_role=ProjectUserRole.TEAM_MANAGER,
)

# Add one Admin to the Project
project.add_users(
    ["[email protected]"],
    user_role=ProjectUserRole.ADMIN,
)

5. Import labels/annotations

After successfully setting up your Project, you are ready to import labels!

Clickable Div Import Labels/Annotations