​
STEP 1: Import Your Files to Encord

​
Create a Cloud Integration

Select your cloud provider.

​
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.
Metadata Schema keys support letters (a-z, A-Z), numbers (0-9), and the following blank spaces ( ), hyphens (-), underscores (_), and periods (.).

​
Custom metadata

Custom metadata refers to any additional information you attach to files, allowing for better data curation and management based on your specific needs. It can include any details relevant to your workflow, helping you organize, filter, and retrieve data more efficiently. 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. Encord uses metadata schemas to validate custom metadata uploaded to Encord and to instruct Index and Active how to display your metadata.

To handle your custom metadata schema across multiple teams within the same organization, 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.

​
Metadata schema table

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.

Use add_scalar to add a scalar key to your metadata schema.

Scalar KeyDescriptionDisplay Benefits
booleanBinary data type with values “true” or “false”.Filtering by binary values
datetimeISO 8601 formatted date and time.Filtering by time and date
numberNumeric data type supporting float values.Filtering by numeric values
uuidUUIDv4 formatted unique identifier for a data unit.Filtering by customer specified unique identifier
varcharTextual data type. Formally string. string can be used as an alias for varchar, but we STRONGLY RECOMMEND that you use varchar.Filtering by string.
textText 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.

KeyDescriptionDisplay Benefits
enumEnumerated type with predefined set of values.Facilitates categorical filtering and data validation

Use add_embedding to add an embedding to your metadata schema.

KeyDescriptionDisplay Benefits
embedding1 to 4096 for Index. 1 to 2000 for Active.Filtering by embeddings, similarity search, 2D scatter plot visualization (Coming Soon)

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.

​
Import your metadata schema to Encord


# 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)

​
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.


# 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)

​
Create a Folder

You must create a folder in Index to store your files.

  1. Navigate to Files under the Index heading in the Encord platform.
  2. Click the + New folder button to create a new folder. A dialog to create a new folder appears.

  1. Give the folder a meaningful name and description.

  2. Click Create to create the folder. The folder is listed in Files.

​
Create JSON or CSV for Registration

To register files from cloud storage into Encord, you must create a JSON or CSV file specifying the files you want to register.

Find helpful scripts for creating JSON and CSV files for the data registration process here.

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.

For a list of supported file formats for each data type, go here
Encord supports file names up to 300 characters in length for any file or video for upload.

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.

BEST PRACTICE: 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 or here for information on using the SDK.

​
Import your data

​
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. Once you have selected a smaller group of images, videos or audio files, create a Collection.

  1. Log in to the Encord platform. The landing page for the Encord platform appears.

  2. Go to Index > Files. The All folders page appears with a list of all folders in Encord.

  3. Click in to a Folder. The landing page for the Folder appears and the Explorer button is enabled.

  4. Click the Explorer button. The Index Explorer page appears.

    Access Index Explorer

  5. Search, sort, and filter your data until you have the subset of the data you need.

    Sort and Filter

  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.

    Selecting a video frame selects the entire video. Specific frames from a video cannot be selected.

    Create Collection in Index

  7. Click Select all to select all the images in the subset.

  8. Click Add to a Collection.

  9. Click New Collection.

  10. Specify a meaningful title and description for the Collection.

    The title specified here is applied as a tag/label to every selected image.

  11. Click Collections to verify the Collection appears in the Collections list.

​
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 labelled.

We recommend learning about Ontology structure in Encord before creating Ontologies.
  1. Click the New ontology button in the Ontologies section to create a new Ontology.

  1. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.

  2. Click Next to continue.

  1. Define your Ontology structure. See our documentation on Ontology structure for more information on the various types of objects, classifications, and attributes.

To add objects:

Ensure that you add Audio Region objects for audio files and Text Region objects for text files.
  1. Click Add object to create a new object.
  2. Give the object a name. For example “Apple”.
  3. Select a shape for the object. For example polygon.
  4. Optionally, enable the Required toggle to mark the object as Required.
  5. Optionally, add attributes to the object.
  6. 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”.

  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:

  1. Click Add classification to create a new classification.
  2. Give the classification a name. For example, “Time of day”.
  3. Optionally, configure the classification. The default classification type is a text field.
  4. Optionally, enable the Required toggle to mark the object as Required.
  5. 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.

  1. Click the arrow icon next to an object to configure the classification.
  1. Click the classification type to change the classification type. The default classification type is a text field.
  2. Click Add option to add an option if you have selected a radio button or check list classification.
  3. Enter a name for the classification option. For example, the classification “Time of day” can have the options “Night” and “Day”.
  4. Click the Back to parent button to return the Ontology creation view.

​
Create a Task Agent

Task 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 Task Agent. The Task Agent executes the configured SDK script for all tasks that are routed through the Task Agent stage in your Workflow.

​
Triggering the Task Agent

Webhooks are coming soon, allowing you to trigger Task Agents manually.

Task Agents aggregate all tasks that reach the Agent stage in the workflow. Your custom script must be triggered at this stage before the tasks proceed further in the workflow.

​
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.

To set up a Workflow template, navigate to the Annotate section of the Encord platform, and click the + New workflow button

1. Add users to the Workflow:

Add users from your Organization to the Workflow by clicking Invite collaborators.

  • 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.
Learn more about managing collaborators in the Managing collaborators section.

2. Configure your Workflow:

The canvas is populated with a simple Workflow by default.

Click the Add stage button to show all Workflow components.

Customize your Workflow by pulling components onto the canvas.

Add the stages and other components you require for your Workflow onto the canvas:

  • All workflows must begin with the Start stage.

  • All workflows must contain an Annotate stage.

  • Add routers to your Project to determine different pathways through your Workflow a task can take.

  • Add as many Review stages as necessary.

  • All workflows must end at a Complete stage.

  • Link all components on the canvas by clicking and dragging from one connection point to another.

All Workflows can be saved as a template by clicking the Save as a new template button.

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.
    • 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.
    • Optionally, add a Webhook to receive notifications when labels are submitted at this stage.
More details about configuring annotation stages can be found in the Annotate section below
  • Click a Review card on the canvas to start editing the review stage.
    • 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.
More details about configuring review stages can be found in the Review section below.

  • Click a Router card on your canvas. See the router section 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 if users in this node should be prevented from being assigned to tasks they completed in the nodes listed.

More details on routers can be found in the router section below.

​
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.

  1. In the Encord platform, select Projects under Annotate.
  2. Click the + New annotation project button to create a new Project.
  1. Give the Project a meaningful title and description.

If you are part of an Organization, an optional 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.

  1. Click the Attach ontology button.

  2. Select an Ontology from the list using the Select button, or create a new Ontology by clicking the New ontology button.

  1. Click OK to attach the Ontology to the Project.

  2. Click the Attach datasets button.

  3. Select a Dataset from the list using the Attach button, or create a new Dataset by clicking the New Dataset button.

  1. Click OK to attach the Dataset(s) to the Project.
  1. Click the Load from template button to use a Workflow template.

  1. Select the template you want to use and click Load template.

  2. 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.

​
STEP 4: Label your Data

Now you are ready to label your data. We recommend you and your team watch these introductory videos.

For more details, see our comprehensive tutorial on labeling here.

​
STEP 5: Export your Labels

Only Project admins can export labels
Descriptions of all information contained in the export file can be found in the export file reference.
  1. Navigate to Labels and export on the Project Dashboard
  2. Select the Data tab.
  3. Select the data units you want to export labels for.
  4. Click the Export and save button. A pop-up appears.
  1. Give this label version a name.
  2. Select whether you want your labels to be exported in JSON or COCO format.
  3. Toggle this if you want to include signed URLs in your export.
  4. Select which label status(es) to include in the export.
  5. Select what objects to include in the export.
  6. Specify the label batching strategy.
  7. Click Export and save to export your labels.