Skip to main content

Annotations

Label your data


Annotations (also known as labels) describe your inputs. When you add inputs to your app, we will create an input level annotation for each input. This input level annotation contains any data you provided in POST /inputs call. Models in your default workflow can also write annotations.

Once your input is successfully indexed, you can add additional annotations, such as concepts and bounding boxes.

Add Annotations

You can label your inputs by calling the POST /annotations endpoint. For example, you can add concept(s) to an image, draw a bounding box, or label concept(s) in a video frame.

When you add an annotation, the app's default workflow will be run by default. This means that any newly added annotations will be immediately available for AI based search and training.

tip

You can add from 1 up to 128 annotations in a single API call.

Each annotation should contain at most one region. If it is a video, each annotation should contain 1 frame. If there are multiple regions in a frame you want to label, you can add multiple annotations for each region and each annotation will be contained within the same frame but in a different region.

info

The initialization code used in the following examples is outlined in detail on the client installation page.

Annotate Images With Concepts

Below is an example of how to annotate a concept present anywhere in an image.

#################################################################################################
# In this section, we set the user authentication, app ID, and how we want to annotate the image.
# Change these strings to run your own example.
#################################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the image you want to annotate
INPUT_ID = "53d0362a9dfa4e03b2293375e2d0db73"
CONCEPT_ID_1 = "tree"
CONCEPT_ID_2 = "water"

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

post_annotations_response = stub.PostAnnotations(
service_pb2.PostAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID_1, value=1.), # 1 means true, this concept is present
resources_pb2.Concept(id=CONCEPT_ID_2, value=0.) # 0 means false, this concept is not present
]
)
)
]
),
metadata=metadata
)

if post_annotations_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_response.status)
raise Exception("Post annotations failed, status: " + post_annotations_response.status.description)

Annotate Images With Multiple Concepts

Below is an example of how to annotate an image with multiple concepts in a single API call. You can provide the concepts in a list and iterate through it.

#################################################################################################
# In this section, we set the user authentication, app ID, and how we want to annotate the image.
# Change these strings to run your own example.
#################################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the image you want to annotate with multiple concepts
INPUT_ID = "53d0362a9dfa4e03b2293375e2d0db73"
CONCEPT_IDS_LIST = ['one', 'two', 'three', 'four', 'five', 'six']

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

post_annotations_response = stub.PostAnnotations(
service_pb2.PostAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
data=resources_pb2.Data(
concepts=[
# We use Python list comprehension to iterate through the list of concepts
resources_pb2.Concept(id=str(i), value=1.) for i in CONCEPT_IDS_LIST
]
)
)
]
),
metadata=metadata
)

if post_annotations_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_response.status)
raise Exception("Post annotations failed, status: " + post_annotations_response.status.description)

Annotate New Bounding Boxes in an Image

Below is an example of how to label a new rectangular bounding box for a region.

These are the bounding box coordinates you need to provide:

  • top_row—The top left of the bounding box normalized to the data dimension to be within [0-1.0];
  • left_col—The left column of the bounding box normalized to the data dimension to be within [0-1.0];
  • bottom_row—The bottom row of the bounding box normalized to the data dimension to be within [0-1.0];
  • right_col—The right col of the bounding box normalized to the data dimension to be within [0-1.0].
########################################################################################
# In this section, we set the user authentication, app ID, and how we want to annotate
# new bounding boxes. Change these strings to run your own example.
#########################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the new bounding boxes you want to annotate
INPUT_ID = "53d0362a9dfa4e03b2293375e2d0db73"
CONCEPT_ID_1 = "tree"
CONCEPT_ID_2 = "water"
CONCEPT_ID_3 = "bike"

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

post_annotations_response = stub.PostAnnotations(
service_pb2.PostAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
data=resources_pb2.Data(
regions=[
resources_pb2.Region(
region_info=resources_pb2.RegionInfo(
bounding_box=resources_pb2.BoundingBox( # draw a bounding box
top_row=0,
left_col=0,
bottom_row=0.5,
right_col=0.5
)
),
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID_1, value=1.), # 1 means true, this concept is present.
resources_pb2.Concept(id=CONCEPT_ID_2, value=0.) # 0 means false, this concept is not present.
]
)
)
]
)

),
resources_pb2.Annotation(
input_id=INPUT_ID,
data=resources_pb2.Data(
regions=[
resources_pb2.Region(
region_info=resources_pb2.RegionInfo(
bounding_box=resources_pb2.BoundingBox( # draw another bounding box
top_row=0.6,
left_col=0.6,
bottom_row=0.8,
right_col=0.8
)
),
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID_3, value=1.), # 1 means true, this concept is present.
]
)
)
]
)

)
]
),
metadata=metadata
)

if post_annotations_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_response.status)
raise Exception("Post annotations failed, status: " + post_annotations_response.status.description)


Annotate Polygons in an Image

Below is an example of how to provide annotations within any polygon-shaped region of an image.

These are the list of points that connect together to form a polygon:

  • row—The row location of the point. This has a [0.0-1.0] range with 0.0 being top row and 1.0 being the bottom row;
  • col—The column location of the point. This has a [0.0-1.0] range with 0.0 being left col and 1.0 being the right col;
  • z—Depth, if applicable, of the point.
#########################################################################################
# In this section, we set the user authentication, app ID, and how we want to annotate
# a polygon. Change these strings to run your own example.
#########################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the polygon you want to annotate
INPUT_ID = "ca8666e974ac4c2c8dfbd7df1e7cbc44"
CONCEPT_ID_1 = "tree"
CONCEPT_ID_2 = "water"
CONCEPT_ID_3 = "bike"

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################


from clarifai_grpc.grpc.api.status import status_code_pb2
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

post_annotations_response = stub.PostAnnotations(
service_pb2.PostAnnotationsRequest(
# The userDataObject is created in the overview and is required when using a PAT
user_app_id=userDataObject,
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
data=resources_pb2.Data(
regions=[
resources_pb2.Region(
region_info=resources_pb2.RegionInfo(
polygon=resources_pb2.Polygon( # draw a polygon
points=[
resources_pb2.Point(row=0.30), # row location of the point, with a [0.0-1.0] range
resources_pb2.Point(col=0.50), # column location of the point, with a [0.0-1.0] range
resources_pb2.Point(z=0.50) # depth, if applicable, of the point
]
)
),
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID_1, value=1), # 1 means true, this concept is present
resources_pb2.Concept(id=CONCEPT_ID_2, value=0) # 0 means false, this concept is not present
]
)
)
]
)

),
resources_pb2.Annotation(
input_id=INPUT_ID,
data=resources_pb2.Data(
regions=[
resources_pb2.Region(
region_info=resources_pb2.RegionInfo(
polygon=resources_pb2.Polygon( # draw another polygon
points=[
resources_pb2.Point(row=0.60),
resources_pb2.Point(col=0.80),
resources_pb2.Point(z=0.50)
]
)
),
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID_3, value=1), # 1 means true, this concept is present
]
)
)
]
)

)
]
),
metadata=metadata
)

if post_annotations_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_response.status)
raise Exception("Post annotations failed, status: " + post_annotations_response.status.description)

Annotate Existing Regions in an Image

When you add an input, detection models (such as Face Detection or General Detection) will detect regions in your image where there appear to be relevant objects. You can get the IDs of these detected regions by listing model's annotations.

Your labels should be contained within Region.data. Each annotation can only have 1 region. If you want to label multiple regions, it is possible to label multiple annotations in a single API call.

Below is an example of how to annotate existing regions in an image.

########################################################################################
# In this section, we set the user authentication, app ID, and how we want to annotate
# existing regions in an image. Change these strings to run your own example.
#########################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the existing regions you want to annotate
INPUT_ID = "53d0362a9dfa4e03b2293375e2d0db73"
CONCEPT_ID_1 = "tree"
CONCEPT_ID_2 = "water"
CONCEPT_ID_3 = "bike"
REGION_ID_1 = "361d6a9253be9152968012660258a4bf"
REGION_ID_2 = "dcfa961b753f3b197d0bf7b242718ab1"

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

post_annotations_response = stub.PostAnnotations(
service_pb2.PostAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
annotations=[
resources_pb2.Annotation( # label a region in this image
input_id=INPUT_ID,
data=resources_pb2.Data(
regions=[
resources_pb2.Region(
id=REGION_ID_1, # this should be a region id returned from list annotations call
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID_1, value=1.), # 1 means true, this concept is present.
resources_pb2.Concept(id=CONCEPT_ID_2, value=0.) # 0 means false, this concept is not present.
]
)
)
]
)

),
resources_pb2.Annotation( # label another region in this image
input_id=INPUT_ID,
data=resources_pb2.Data(
regions=[
resources_pb2.Region(
id=REGION_ID_2 , # this should be a region id returned from list annotations call
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID_3, value=1.), # 1 means true, this concept is present.
]
)
)
]
)

),
]
),
metadata=metadata
)


if post_annotations_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_response.status)
raise Exception("Post annotations failed, status: " + post_annotations_response.status.description)

Annotate Images With Different user_id and status

Each annotation is tied to a user or a model in your workflow. By default, when a user posts an annotation, this user is the owner of the annotation.

Sometimes, however, you might want to post an annotation as another user; for example, when assigning an image to another user. In such a case, you can create an annotation with another user_id (and status PENDING).

note

Only the app owner can post an annotation with other user's user_id; collaborators cannot.

Below is an example of how to annotate images with different user_id and status.

#########################################################################
# In this section, we set the user authentication, app ID, input ID,
# and another user ID. Change these strings to run your own example.
#########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to post your own annotations
INPUT_ID = 'e838fac8da9d40c89f2291a6496593da'
ANOTHER_USER_ID = 'ANOTHER_USER_ID_HERE'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2, status_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID) # The userDataObject is created in the overview and is required when using a PAT

post_annotations_response = stub.PostAnnotations(
service_pb2.PostAnnotationsRequest(
user_app_id=userDataObject,
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
user_id=ANOTHER_USER_ID, # If empty, it is the user who posts this annotation
status=status_pb2.Status(
code=status_code_pb2.ANNOTATION_PENDING # annotation pending status. By default success.
),
)
]
),
metadata=metadata
)

if post_annotations_response.status.code != status_code_pb2.SUCCESS:
print(post_annotations_response.status)
raise Exception("Post annotations failed, status: " + post_annotations_response.status.description)

List Annotations

You can get a list of annotations within your app with a GET call. Annotations will be returned from oldest to newest.

These requests are paginated. By default each page will return 20 annotations.

List All User Created Annotations in Your App

Below is an example of how to list all your user labelled annotations.

note

This will not show annotations by models in your workflow. To include model created annotations, you need to set list_all_annotations to True.

##################################################################
# In this section, we set the user authentication and app ID.
# Change these strings to run your own example.
##################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
service_pb2.ListAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
per_page=10
),
metadata=metadata
)

if list_annotations_response.status.code != status_code_pb2.SUCCESS:
print(list_annotations_response.status)
raise Exception("List annotations failed, status: " + list_annotations_response.status.description)

for annotation_object in list_annotations_response.annotations:
print(annotation_object)

List All Annotations in Your App

Below is an example of how to list all annotations, including those created by models.

##################################################################
# In this section, we set the user authentication and app ID.
# Change these strings to run your own example.
##################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
service_pb2.ListAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
per_page=10,
list_all_annotations=True
),
metadata=metadata
)

if list_annotations_response.status.code != status_code_pb2.SUCCESS:
print(list_annotations_response.status)
raise Exception("List annotations failed, status: " + list_annotations_response.status.description)

for annotation_object in list_annotations_response.annotations:
print(annotation_object)

List User Created Annotations by Input IDs

Below is an example of how to list all user created annotations for certain input (one or several) by providing a list of input IDs.

note

This will not show annotations by models in your workflow. To include model created annotations, you need to set list_all_annotations to True.

#########################################################################
# In this section, we set the user authentication, app ID, and input IDs
# Change these strings to run your own example.
#########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to list your own annotations
INPUT_ID_1 = '53d0362a9dfa4e03b2293375e2d0db73'
INPUT_ID_2 = '00f6d742124147ac8ca7788f73736fb9'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
service_pb2.ListAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
input_ids=[INPUT_ID_1, INPUT_ID_2],
per_page=10
),
metadata=metadata
)

if list_annotations_response.status.code != status_code_pb2.SUCCESS:
print(list_annotations_response.status)
raise Exception("List annotations failed, status: " + list_annotations_response.status.description)

for annotation_object in list_annotations_response.annotations:
print(annotation_object)

List Annotations by Input IDs and Annotation IDs

You can list annotations by input IDs and their corresponding annotation IDs. Number of input IDs and annotation IDs should be the same. Since we are finding annotation by IDs, this will match any user or model created annotations.

Below is an example of how to do that.

tip
  • When listing annotations, both input IDs and annotation IDs are optional. If you do not provide any input ID or annotation ID, we will return all annotations based on the creation time of each input.

  • You can also list annotations by providing input IDs only.

  • However, if you want to list annotations by providing annotation IDs, then input IDs are also required so that we know the inputs that correspond to the annotation IDs provided in the request. In this case, the number of input IDs should be equal to the number of annotation IDs.

##########################################################################
# In this section, we set the user authentication, app ID, input IDs, and
# annotation IDs. Change these strings to run your own example.
##########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to list your own annotations
INPUT_ID_1 = '53d0362a9dfa4e03b2293375e2d0db73'
INPUT_ID_2 = '00f6d742124147ac8ca7788f73736fb9'
ANNOTATION_ID_1 = '300b8e39a65e4f33ae4e15e86eaf4a3b'
ANNOTATION_ID_2 = 'fcd19d4ad96440e7b1fbda7279c19e44'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
service_pb2.ListAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
input_ids=[INPUT_ID_1, INPUT_ID_2],
ids=[ANNOTATION_ID_1, ANNOTATION_ID_2],
per_page=10
),
metadata=metadata
)

if list_annotations_response.status.code != status_code_pb2.SUCCESS:
print(list_annotations_response.status)
raise Exception("List annotations failed, status: " + list_annotations_response.status.description)

for annotation_object in list_annotations_response.annotations:
print(annotation_object)

List Annotations by User IDs

An annotation is created by either a user or a model. You can list annotations created by specific user(s) by providing their user IDs.

Below is an example of how to do that.

#########################################################################
# In this section, we set the user authentication, app ID, and user IDs.
# Change these strings to run your own example.
#########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Insert the user IDs
USER_ID_1 = 'USER_ID_1_HERE'
USER_ID_2 = 'USER_ID_2_HERE'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
service_pb2.ListAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
user_ids=[USER_ID_1, USER_ID_2],
per_page=10
),
metadata=metadata
)

if list_annotations_response.status.code != status_code_pb2.SUCCESS:
print(list_annotations_response.status)
raise Exception("List annotations failed, status: " + list_annotations_response.status.description)

for annotation_object in list_annotations_response.annotations:
print(annotation_object)

List Annotations by Model Version IDs

An annotation is created by either a user or a model. For example, if your workflow has a detection model, when you add an input, the model will detect objects in your input. You can see these detected objects by listing the annotations created in the detection model.

You can also label these regions by using Post annotation with the region ID returned from this call.

Below is an example of how to list annotations by model version IDs.

##################################################################################
# In this section, we set the user authentication, app ID, and model version IDs.
# Change these strings to run your own example.
##################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Insert the model version IDs
MODEL_VERSION_ID_1 = 'MODEL_VERSION_ID_1_HERE'
MODEL_VERSION_ID_2 = 'MODEL_VERSION_ID_2_HERE'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

list_annotations_response = stub.ListAnnotations(
service_pb2.ListAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
model_version_ids=[MODEL_VERSION_ID_1, MODEL_VERSION_ID_2],
per_page=10
),
metadata=metadata
)

if list_annotations_response.status.code != status_code_pb2.SUCCESS:
print(list_annotations_response.status)
raise Exception("List annotations failed, status: " + list_annotations_response.status.description)

for annotation_object in list_annotations_response.annotations:
print(annotation_object)

Update Annotations

Changing annotation data is possible by PATCHing existing annotations. The application owner can change any user-created annotations. Collaborators are not allowed to change annotations made by other collaborators.

Generally speaking, you should send PATCH when you want to change the data you have posted; for example, changing the concept from positive to negative or adjusting the bounding box coordinates.

If you want to add more tags, you can always POST new annotations. There is no limit on how many annotations an input can have.

Update supports overwrite, merge, and remove actions. You can update from 1 up to 128 annotations in a single API call.

Update Annotation With Concepts

Below is an example of how to update an annotation of an image with a new concept, or change a concept value from true to false (or vice versa).

####################################################################################
# In this section, we set the user authentication, app ID, input ID, annotation ID,
# and concept ID. Change these strings to run your own example.
####################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the annotation you want to update
INPUT_ID = '53d0362a9dfa4e03b2293375e2d0db73'
ANNOTATION_ID = '300b8e39a65e4f33ae4e15e86eaf4a3b'
CONCEPT_ID = 'apple'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

patch_annotations_response = stub.PatchAnnotations(
service_pb2.PatchAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
action="merge", # Supported actions: overwrite, merge, remove.
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
id=ANNOTATION_ID,
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID, value=1.) # 1 means true, this concept is present.
]
)
)
]
),
metadata=metadata
)

if patch_annotations_response.status.code != status_code_pb2.SUCCESS:
print(patch_annotations_response.status)
raise Exception("Patch annotations failed, status: " + patch_annotations_response.status.description)

Update Annotation With Concepts in a Region

When you update region data, you must nest this new data within region.data. Set the region_id to the current region_id if you do not want to change or remove this region.

Below is an example of how to update annotation with concepts in a region.

####################################################################################
# In this section, we set the user authentication, app ID, input ID, annotation ID,
# concept ID, and region ID. Change these strings to run your own example.
####################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the annotation you want to update
INPUT_ID = '53d0362a9dfa4e03b2293375e2d0db73'
ANNOTATION_ID = '300b8e39a65e4f33ae4e15e86eaf4a3b'
CONCEPT_ID = 'tree'
REGION_ID = '361d6a9253be9152968012660258a4bf'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

patch_annotations_response = stub.PatchAnnotations(
service_pb2.PatchAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
action="merge", # Supported actions: overwrite, merge, remove.
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
id=ANNOTATION_ID,
data=resources_pb2.Data(
regions=[
resources_pb2.Region(
id=REGION_ID, # this should be the region id of this annotation before patch
data=resources_pb2.Data(
concepts=[
resources_pb2.Concept(id=CONCEPT_ID, value=1.), # 1 means true, this concept is present.
]
)
)
]
)
)
]
),
metadata=metadata
)

if patch_annotations_response.status.code != status_code_pb2.SUCCESS:
print(patch_annotations_response.status)
raise Exception("Patch annotations failed, status: " + patch_annotations_response.status.description)

Update Annotation Region Coordinates

You can update region bounding boxes coordinates. When changing the region, you should use overwrite action. With overwrite action, you need to provide the data you want to keep in this annotation.

Below is an example of how to do that.

####################################################################################
# In this section, we set the user authentication, app ID, input ID, annotation ID,
# and concept ID. Change these strings to run your own example.
#####################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the annotation you want to update
INPUT_ID = '53d0362a9dfa4e03b2293375e2d0db73'
ANNOTATION_ID = '300b8e39a65e4f33ae4e15e86eaf4a3b'
CONCEPT_ID = 'bike'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

patch_annotations_response = stub.PatchAnnotations(
service_pb2.PatchAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
action="overwrite",
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
id=ANNOTATION_ID,
data=resources_pb2.Data(
regions=[
resources_pb2.Region(
region_info=resources_pb2.RegionInfo(
bounding_box=resources_pb2.BoundingBox( # move bounding box to new coordinates
top_row=0.5,
left_col=0.5,
bottom_row=0.8,
right_col=0.8
)
),
data=resources_pb2.Data( # need to provide tags you previously labeled since this is overwrite action
concepts=[
resources_pb2.Concept(id=CONCEPT_ID, value=1.), # 1 means true, this concept is present.
]
)
)
]
)
)
]
),
metadata=metadata
)

if patch_annotations_response.status.code != status_code_pb2.SUCCESS:
print(patch_annotations_response.status)
raise Exception("Patch annotations failed, status: " + patch_annotations_response.status.description)

Update Annotation Status

Below is an example of how to update an annotation status.

#############################################################################
# In this section, we set the user authentication, app ID, input ID, and
# annotation ID. Change these strings to run your own example.
#############################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the annotation status you want to update
INPUT_ID = 'c021c670357e4083b197abe80bda82b0'
ANNOTATION_ID = '8ac7fd96ce6f44b8a0f4806488b41b93'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2, status_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

patch_annotations_response = stub.PatchAnnotations(
service_pb2.PatchAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
action="merge", # Supported actions: overwrite, merge, remove.
annotations=[
resources_pb2.Annotation(
input_id=INPUT_ID,
id=ANNOTATION_ID,
status=status_pb2.Status(
code=status_code_pb2.ANNOTATION_SUCCESS
)
)
]
),
metadata=metadata
)

if patch_annotations_response.status.code != status_code_pb2.SUCCESS:
print(patch_annotations_response.status)
raise Exception("Patch annotations failed, status: " + patch_annotations_response.status.description)

Delete Annotations

Delete Annotation by Input ID and Annotation ID

Below is an example of how to delete a single annotation by input ID and annotation ID.

#####################################################################
# In this section, we set the user authentication, app ID, input ID,
# and annotation ID. Change these strings to run your own example.
#####################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the annotation you want to delete
INPUT_ID = '53d0362a9dfa4e03b2293375e2d0db73'
ANNOTATION_ID = '300b8e39a65e4f33ae4e15e86eaf4a3b'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

delete_annotation_response = stub.DeleteAnnotation(
service_pb2.DeleteAnnotationRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
input_id=INPUT_ID,
annotation_id=ANNOTATION_ID
),
metadata=metadata
)

if delete_annotation_response.status.code != status_code_pb2.SUCCESS:
print(delete_annotation_response.status)
raise Exception("Delete annotations failed, status: " + delete_annotation_response.status.description)

Bulk Delete Annotations by Input IDs and Annotation IDs

You can delete multiple annotations in one API call. You need to provide a list of input IDs and a list of annotation IDs. The number of input IDs has to match the number of annotation IDs.

Below is an example of how to do that.

#######################################################################
# In this section, we set the user authentication, app ID, input IDs,
# and annotation IDs. Change these strings to run your own example.
#######################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the annotations you want to bulk delete
INPUT_ID_1 = 'b76fe0adb0294906942f169bb1f6cacf'
INPUT_ID_2 = 'e838fac8da9d40c89f2291a6496593da'
ANNOTATION_ID_1 = '35c37cda9ad8460fae12b2b2b6a23f1d'
ANNOTATION_ID_2 = '63d69000ae3343d0b70b892ea3dcb01d'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

delete_annotations_response = stub.DeleteAnnotations(
service_pb2.DeleteAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
input_ids=[INPUT_ID_1, INPUT_ID_2],
ids=[ANNOTATION_ID_1, ANNOTATION_ID_2]
),
metadata=metadata
)

if delete_annotations_response.status.code != status_code_pb2.SUCCESS:
print(delete_annotations_response.status)
raise Exception("Delete annotations failed, status: " + delete_annotations_response.status.description)

Bulk Delete All Annotations by Input IDs

To delete all annotations of a given input, you just need to set their input ID(s). This will delete all annotations for these input(s), EXCEPT the input level annotations, which only get deleted if you delete the inputs themselves.

Below is an example of how to do that.

##########################################################################
# In this section, we set the user authentication, app ID, and input IDs.
# Change these strings to run your own example.
##########################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these based on the annotations you want to bulk delete
INPUT_ID_1 = '53d0362a9dfa4e03b2293375e2d0db73'
INPUT_ID_2 = '00f6d742124147ac8ca7788f73736fb9'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

delete_annotations_response = stub.DeleteAnnotations(
service_pb2.DeleteAnnotationsRequest(
user_app_id=userDataObject, # The userDataObject is created in the overview and is required when using a PAT
input_ids=[INPUT_ID_1, INPUT_ID_2]
),
metadata=metadata
)

if delete_annotations_response.status.code != status_code_pb2.SUCCESS:
print(delete_annotations_response.status)
raise Exception("Delete annotations failed, status: " + delete_annotations_response.status.description)