Issues & Comments in Projects

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.

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"])

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", [])

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.

Manage Project Issue Tags

Issue tags must be linked to a Project before you can use them on issues. Use project.get_issue_tags() to list the issue tags linked to a Project, and project.add_issue_tags() to link existing Workspace issue tags to a Project by name.

# 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,
    # For US platform users use domain="https://api.us.encord.com"
    domain="https://api.encord.com",
)

project = user_client.get_project(PROJECT_ID)

# Link existing Workspace issue tags to the Project
project.add_issue_tags(["<issue-tag-1>", "<issue-tag-2>"])

# List all issue tags linked to the Project
for issue_tag in project.get_issue_tags():
    print(issue_tag.name, issue_tag.uuid)

Create Issues on Annotations

Use task.issues.add_annotation_issue() to anchor an issue to a specific object or classification instance. Pass the instance’s object_hash (or classification_hash) as annotation_id. Leave frame_ranges empty to flag the instance on every frame it appears on, or pass one or more inclusive IssueFrameRange values to flag it on specific frames. For Data Groups and Scenes, use space_id to specify the space the annotation belongs to.

# Import dependencies
from encord import EncordUserClient
from encord.issues import IssueFrameRange
from encord.workflow import ReviewStage

SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"
REVIEW_STAGE_NAME = "<name-of-review-stage>"

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)
review_stage = project.workflow.get_stage(name=REVIEW_STAGE_NAME, type_=ReviewStage)

for task in review_stage.get_tasks():
    label_row = project.list_label_rows_v2(data_hashes=[task.data_hash])[0]
    label_row.initialise_labels()

    for object_instance in label_row.get_object_instances():
        # Flag the whole object instance, for example for a wrong attribute value
        task.issues.add_annotation_issue(
            annotation_id=object_instance.object_hash,
            comment="Wrong attribute value",
            issue_tags=["<issue-tag-1>"],
        )

        # Flag the object instance on frames 30 to 45 only (inclusive)
        task.issues.add_annotation_issue(
            annotation_id=object_instance.object_hash,
            comment="Bad contour on frames 30-45",
            issue_tags=["<issue-tag-1>"],
            frame_ranges=[IssueFrameRange(start=30, end=45)],
        )

# Pin an issue to a 3D coordinate (in scene space) on frame 0 of a Scene
task.issues.add_scene_coordinate_issue(
    frame_index=0,
    x=1.5,
    y=-2.0,
    z=0.3,
    comment="Missing cuboid for this vehicle",
    issue_tags=["<issue-tag-1>"],
)

Supported Modalities

Not all modalities support all issue types.

Modality	File	Frame	Pinned/Coordinate
Images	✅	❌	✅
Videos	✅	✅	✅
Audio files	✅	✅	❌
Text files	✅	❌	❌
HTML files	✅	❌	❌
PDFs	✅	✅	✅
DICOM	✅	✅	✅
NifTi	✅	✅	✅

Using Issues SDK

The following code provides an example of how you are likely going to use the SDK with Issues/Comments. ANNOTATE stage

Issues/comments are added to the specified data units.
A label is added to the data unit.
The task is submitted for review.

REVIEW stage

Issues/comments are added to the specified data units.
The task is rejected.

Issues/Comments Annotate and Review Example

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

Your Service Account MUST be added to the Project as an Admin to delete Issues.

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

# 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,
    # For US platform users use "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(data_title=DATA_TITLE):
    issues_to_delete = list(task.issues.list())
    task.issues.delete(issues_to_delete)

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

# 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,
    # For US platform users use "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 issue.comments and issue.comments[0].author_email == AUTHOR_EMAIL:
            issues_to_delete.append(issue)

    task.issues.delete(issues_to_delete)

Get Started

General

Data

Ontologies

Projects

Labels

DICOM

Issues & Comments in Projects

Create Issues

Manage Project Issue Tags

Create Issues on Annotations

Supported Modalities

Using Issues SDK

Delete Issues

​Create Issues

​Manage Project Issue Tags

​Create Issues on Annotations

​Supported Modalities

​Using Issues SDK

​Delete Issues

Create Issues

Manage Project Issue Tags

Create Issues on Annotations

Supported Modalities

Using Issues SDK

Delete Issues