Create Lidar Cuboid Annotation
This endpoint creates a lidarannotation task. In this task, one of our Scalers view outputs from a series of LIDAR frames, along with optional radar and camera data, and annotate where different objects exist in the 3D space with 3D cuboids. The required parameters for this task are attachments, labels, and attachment_type. The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callback section. The attachments will be a list of links to external JSON files, each following the definition of a Frame as specified below.
Body Params
projectstring
The name of the project to associate this task with. See the Projects Section for more details.
batchstring
The name of the batch to associate this task with. Note that if a batch is specified, you need not specify the project, as the task will automatically be associated with the batch's project. For Scale Rapid projects specifying a batch is required. See Batches section for more details.
instructionstring
A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use markdown to show example images, give structure to your instructions, and more. See our instruction best practices for more details. For Scale Rapid projects, DO NOT set this field unless you specifically want to override the project level instructions.
callback_urlstring
The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
attachmentsarray of stringsrequired
A list of URLs to the Frame objects you’d like to be labeled. The frames should be time-ordered as is natural. The URLs should link to JSON files that follows the specification above, Callback section, or protobuf files that encode LidarFrame messages as defined in the .proto file.
attachment_typestringrequired
Describes what type of file the attachment is. Defaults to json, but should be set to protobuf if attachments are being sent in protobuf format.
labelsarray of stringsrequired
An array of strings or objects describing the different types of objects you’d like to be used to segment the image. You may include at most 50 objects. See Label Nesting and Options for more details about label objects.
annotation_attributesobject
This field is used to add additional attributes that you would like to capture per annotation. See Annotation Attributes for more details about annotation attributes.
max_distance_metersinteger
The maximum distance in meters from the sensor for which an object should be labeled. If undefined, all visible objects will be labeled.
meters_per_unitinteger
The conversion rate of a unit scalar in the point data to a meter in the real world. e.g. if a unit vector represents 10 meters in real world distance, then this value should be 10.
frames_per_secondinteger
The frequency of the frames per second.
labeling_sample_rateinteger
The sample rate of frames which will be fully labeled. If you are capturing 10Hz LIDAR but only want labels in 2Hz, you can set this parameter to 5 and achieve that. If the sample rate is k and there are n frames total, we will fully label (1-indexed), the 1st, k + 1-th, 2k + 1-th, ... , floor((n - 1) / k) * k + 1-th, and nth frames.
polygons_enabledboolean
Enables polygon annotations, see the Polygons section in Response on Callback for more details.
polygons_labelsarray of strings
An array of strings describing the different types of polygons you'd like to be annotated in the scene.
metadataobject
A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format. Max 10KB.
priorityinteger
A value of 10, 20, or 30 that defines the priority of a task within a project. The higher the number, the higher the priority.
unique_idstring
A arbitrary ID that you can assign to a task and then query for later. This ID must be unique across all projects under your account, otherwise the task submission will be rejected. See Avoiding Duplicate Tasks for more details.
clear_unique_id_on_errorboolean
If set to be true, if a task errors out after being submitted, the unique id on the task will be unset. This param allows workflows where you can re-submit the same unique id to recover from errors automatically
tagsarray of strings
Arbitrary labels that you can assign to a task. At most 5 tags are allowed per task. You can query tasks with specific tags through the task retrieval API.
Request
import requests
url = "https://api.scale.com/v1/task/lidarannotation"
payload = {
"instruction": "Annotate the *vehicles* and *pedestrians* in the image.",
"callback_url": "https://example.com/callback",
"attachments": ["https://s3-us-west-1.amazonaws.com/scaleapi-cust-lidar/kitti-road-2011_10_03_drive_0047/frames/frame1.json"],
"attachment_type": "json",
"labels": ["Vehicle"],
"priority": None
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "<YOU_API_KEY>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)from scaleapi.tasks import TaskType
from scaleapi.exceptions import ScaleDuplicateResource
payload = dict(
"instruction": "Annotate the *vehicles* and *pedestrians* in the image.",
"callback_url": "https://example.com/callback",
"attachments": ["https://s3-us-west-1.amazonaws.com/scaleapi-cust-lidar/kitti-road-2011_10_03_drive_0047/frames/frame1.json"],
"attachment_type": "json",
"labels": ["Vehicle"],
"priority": None
)
try:
client.create_task(TaskType.LidarAnnotation, **payload)
except ScaleDuplicateResource as err:
print(err.message) # If unique_id is already used for a different taskResponse
{
"callback_url": "http://www.example.com/callback",
"created_at": "2019-01-16T21:03:33.166Z",
"instruction": "Annotate the *vehicles* and *pedestrians* in the image.",
"is_test": false,
"params": {},
"status": "pending",
"task_id": "5a99e20de50d4979ce6d291e",
"type": "lidarannotation"
}Create Lidar Segmentation Annotation
This endpoint creates a lidarsegmentation task. In this task, one of our Taskers views outputs from a series of LIDAR frames, along with optional camera data, and annotates where different objects exist in the 3D space by assigning a class to each LidarPoint.\n\nThis type of task can be created on its own, or you can create a task based on an already completed Lidar Annotation task.\n\nThe required parameters for this task are labels, attachments, and attachment_type. \n\n* The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the callbacks section. \n* The labels array lists the object classes for which semantic information is desired.\n\t* Instance labels are supported, by specifying instance_label: true when defining the label. For example, ['Road', {'choice': 'Pedestrian', 'instance_label': true}].\n\t* Nested labels are also supported for these labels, and may be specified in the same format as noted in our documentation. For example, ['Vehicle', {'choice': 'Pedestrian', 'subchoices': ['Adult', 'Child']}].\n* The attachments will be a list of links to external JSON files, each following the definition of a Frame as specified here.
You should provide additional markdown-enabled instructions via the instruction parameter.\n\nIt is strongly recommended for you to flesh out your Markdown instructions with many examples of tasks being done correctly and incorrectly.\n\nIf successful, Scale will immediately return the generated task object, of which you should at least store the task_id
Body Params
projectstring
The name of the batch to associate this task with. Note that if a batch is specified, you need not specify the project, as the task will automatically be associated with the batch's project. For Scale Rapid projects specifying a batch is required. See Batches section for more details.
batchstring
The name of the batch to associate this task with. Note that if a batch is specified, you need not specify the project, as the task will automatically be associated with the batch's project. For Scale Rapid projects specifying a batch is required. See Batches section for more details.
instructionstring
A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use markdown to show example images, give structure to your instructions, and more. See our instruction best practices for more details. For Scale Rapid projects, DO NOT set this field unless you specifically want to override the project level instruction
callback_urlstring
The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
attachmentsarray of strings
A list of URLs to the Frame objects you’d like to be labeled. The frames should be time-ordered as is natural. The URLs should link to JSON files that follows the specification above Callback section, or protobuf files that encode LidarFrame messages as defined in the .proto file.
attachment_typestringrequired
Describes what type of file the attachment is. Defaults to json, but should be set to protobuf if attachments are being sent in protobuf format.
labelsarray of strings
An array of strings or objects describing the different types of objects you’d like to be used to segment the image. You may include at most 50 objects. See Label Nesting and Options for more details about label objects.
metadataobject
A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format. Max 10KB.
priorityinteger
A value of 10, 20, or 30 that defines the priority of a task within a project. The higher the number, the higher the priority.
unique_idobject
A arbitrary ID that you can assign to a task and then query for later. This ID must be unique across all projects under your account, otherwise the task submission will be rejected. See Avoiding Duplicate Tasks for more details
clear_unique_id_on_errorboolean
If set to be true, if a task errors out after being submitted, the unique id on the task will be unset. This param allows workflows where you can re-submit the same unique id to recover from errors automatically
tagsarray of strings
Arbitrary labels that you can assign to a task. At most 5 tags are allowed per task. You can query tasks with specific tags through the task retrieval API.
Request
import requests
url = "https://api.scale.com/v1/task/lidarsegmentation"
payload = {
"instruction": "**Instructions:** Please label all the things",
"callback_url": "https://example.com/callback",
"attachments": ["https://s3-us-west-1.amazonaws.com/scaleapi-cust-lidar/kitti-road-2011_10_03_drive_0047/frames/frame1.json"],
"attachment_type": "json",
"labels": ["Vegetation"],
"priority": None
}
headers = {
"accept": "application/json",
"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)Response
{
"callback_url": "http://www.example.com/callback",
"created_at": "2019-01-16T21:03:33.166Z",
"instruction": "Segment the *Vegetation* in the image.",
"is_test": false,
"params": {},
"status": "pending",
"task_id": "5a99e20de50d4979ce6d291e",
"type": "lidarsegmentation"
}Create Lidar Linking Annotation
This endpoint creates a lidarlinking task. Sometimes camera calibrations can be incorrect in 3D tasks, leading to inaccurate projections of the cuboid vertices onto 2D images (despite the 3D cuboids being accurate). The 2D/3D linking API allows users to request corrected 2D projections, each labeled with the same ID as the corresponding cuboid in 3D.
The required parameters for this task are lidar_task, annotation_type, and instruction. The lidar_task is the ID of the completed lidar task to request corrected 2D projections. The annotation_type is the 2D annotation type to return, either imageannotation (preferred), annotation, cuboidannotation, or polygonannotation. The format of these annotation types is described in more detail in box, cuboid, polygon, and imageannotation documentation, respectively.
You must provide additional markdown-enabled instructions via the instruction parameter.
It is strongly recommended for you to flesh out your Markdown instructions with many examples of tasks being done correctly and incorrectly.
If successful, Scale will immediately return the generated task object, of which you should at least store the task_id.
lidarlinking tasks can also be created automatically after a lidarannotation or lidarsegmentation task is completed. To learn more about this, see Dependent Tasks.
Body Params
projectstring
The name of the project to associate this task with.
batchstring
The name of the batch to associate this task with. Note that if a batch is specified, you need not specify the project, as the task will automatically be associated with the batch's project. For Scale Rapid projects specifying a batch is required. See Batches section for more details.
instructionstring
A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use markdown to show example images, give structure to your instructions, and more. See our instruction best practices for more details. For Scale Rapid projects, DO NOT set this field unless you specifically want to override the project level instructions.
callback_urlstring
The full url (including the scheme http:// or https://) or email address of the callback that will be used when the task is completed.
annotation_typestringrequired
The 2D annotation type to return, either imageannotation (preferred), annotation, cuboidannotation, or polygonannotation
lidar_taskstringrequired
The ID of the completed lidar task to request corrected 2D projections for.
annotation_attributesobject
This field is used to add additional attributes that you would like to capture per annotation. See Annotation Attributes for more details about annotation attributes.
camera_idsarray of integers
Indices of the CameraImages in the lidarannotation task to request corrected 2D projections for. Defaults to all cameras.
events_to_annotatearray of strings
The list of events to annotate. By default, we will annotate every event in each camera, but we can specify which camera we want to annotate specific events in (see event_camera_ids)
event_camera_idsarray of objects
Can be used to specify which cameras we want to annotate each event in. By default we annotate every event in for every camera. Every event specified here must also be in events_to_annotate
can_add_annotationsboolean
Whether or not to allow labelers to draw additional annotations onto the images (note that newly drawn annotations may not have consistent IDs across cameras). True by default.
can_edit_annotationsboolean
Whether or not to allow labelers to modify any aspect of an annotation (labels, attributes and position). True by default.
can_edit_annotation_positionsboolean
Whether or not to allow labelers to modify an annotation's position (but not neceesarily its label or attributes). can_edit_annotations must also be set to true. True by default.
can_delete_annotationsboolean
Whether or not to allow labelers to delete an annotation that was carried over from the lidarannotation task. can_edit_annotations must also be set to true. True by default.
labeling_sample_rateinteger
The sample rate of frames whose 2D projections will be adjusted. If you are capturing 10Hz LIDAR but only want adjusted labels in 2Hz, you can set this parameter to 5 and achieve that. If the sample rate is k and there are n frames total, we will adjust (1-indexed), the 1st, k + 1-th, 2k + 1-th, ... , floor((n - 1) / k) * k + 1-th, and nth frames' projections. Note that labeling_sample_rate samples from the set of frames that are left after the sampling done in the original lidar task; e.g. if you submit a lidar task with 20 frames and labeling_sample_rate=4, frames [1, 5, 9, 13, 17, 20] will be labeled with cuboids. A subsequent lidar linking task with labeling_sample_rate=2 performed on the aforementioned task will label frames [1, 9, 17, 20].
additional_labelsarray of strings
An array of strings or LabelDescription objects to be merged with the original lidarannotation task's list of labels. Defaults to an empty array. Do not use if annotation_type=imageannotation; specify additional labels using geometries instead.
skip_labelsarray of strings
Labels to skip projection generation for (must be a subset of the labels param of the original lidarannotation task). Defaults to an empty array.
geometriesboolean
(required if annotation_type=imageannotation).
An object mapping box, polygon, line, point, cuboid, or ellipseto Geometry objects, indicating the geometry with which annotations should be drawn and the geometry of generated projections.
default_geometrystring
(required if annotation_type=imageannotation). The default geometry to use when creating projections for annotations if the label to geometry mapping isn't explicitly specified in geometries. Must be box, cuboid, or polygon.
copy_all_lidar_task_attributesboolean
If set, all attributes from the lidar_task will be copied to the linking task -- see Inherited Lidar Attributes for details.
paddinginteger
The amount of padding in pixels added to the top, bottom, left, and right of each video frame. This allows labelers to extend annotations outside of the image. 0 by default.
paddingXinteger
The amount of padding in pixels added to the left and right of each video frame. Overrides padding if set. 0 by default.
paddingYinteger
The amount of padding in pixels added to the top and bottom of each video frame. Overrides padding if set. 0 by default.
layersarray of strings
Read-only shapes to be drawn on each frame of the lidarlinking task. Each LidarLinkingLayers object has a required url field, which is a string link to a Scale-accessible file containing an array of Layers, one for each frame of the lidarlinking task. See example file for reference. Each LidarLinkingLayers object also has a required camera_id field (which is an integer describing the camera ID to which the Layers correspond to). It is not required to define LidarLinkingLayers for every camera.
metadataobject
A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format. Max 10KB.
priorityinteger
A value of 10, 20, or 30 that defines the priority of a task within a project. The higher the number, the higher the priority.
unique_idstring
A arbitrary ID that you can assign to a task and then query for later. This ID must be unique across all projects under your account, otherwise the task submission will be rejected. See Avoiding Duplicate Tasks for more details.
clear_unique_id_on_errorboolean
If set to be true, if a task errors out after being submitted, the unique id on the task will be unset. This param allows workflows where you can re-submit the same unique id to recover from errors automatically
tagsarray of strings
Arbitrary labels that you can assign to a task. At most 5 tags are allowed per task. You can query tasks with specific tags through the task retrieval API.
Request
import requests
url = "https://api.scale.com/v1/task/lidarlinking"
payload = {
"instruction": "**Instructions:** Please label all the things",
"annotation_type": "imageannotation",
"can_add_annotations": True,
"can_edit_annotations": True,
"can_edit_annotation_positions": True,
"can_delete_annotations": True,
"lidar_task": "607385eadfd77d0029a84084"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "<YOUR_API_KEY>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)Response
{
"task_id": "string",
"created_at": "string",
"type": "lidarlinking",
"status": "pending",
"instruction": "string",
"is_test": false,
"urgency": "standard",
"metadata": {},
"project": "string",
"callback_url": "string",
"updated_at": "string",
"work_started": false,
"params": {
"labeling_sample_rate": 1,
"geometries": [],
"annotation_type": "imageannotation",
"task_id": "607385eadfd77d0029a84084",
"default_geometry": "box"
}
}
Create Lidar Topdown Tasks
This endpoint creates a lidartopdown task for annotating a collection of lidar Frames in top down, with vector geometric shapes. The available geometries are polygon, line, and point.
Given a collection of LiDAR Frames, and optional camera data, Scale will annotate the top down images with the specified geometries. The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callback section. The attachments will be a list of links to external JSON files, each following the definition of a Frame.
Body Params
projectstring
The name of the project to associate this task with. See the Projects Section for more details.
batchstring
The name of the batch to associate this task with. Note that if a batch is specified, you need not specify the project, as the task will automatically be associated with the batch's project. See Batches section for more details.
instructionstring
A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use markdown to show example images, give structure to your instructions, and more. See our instruction best practices for more details.
callback_urlstring
The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
attachmentarray of stringsrequired
required if attachments is not specified. The full url of an image (png, jpg), to serve as the TopDown aerial imagery for a task to be labeled upon. If an attachment is submitted, the attachments fields should be empty, and vice versa. If a LiDAR task and not an aerial image task, an attachment will be automatically generated by projecting the points in the set of attachments.
attachmentsarray of stringsrequired
A list of URLs to the Frame objects you’d like to be labeled. The frames should be time-ordered as is natural. The URLs should link to JSON files that follows the specification above, Callback section, or protobuf files that encode LidarFrame messages as defined in the .proto file.
region_of_interest_2dobject
required for aerial imagery tasks when submitting type world_camera. This object allows Scale to perform the correct transformation from lon/lat world coordinates to pixels. It allows Scale to identify the pixel coordinates of the camera location on the provided aerial imagery task. If this is not provided, the camera context images will not render on the task.
region_of_interest_3dobject
required for lidar tasks. This Object crops the attachments’ points to a rectangle on the XY plane centered around position with rotation counterclockwise to the z-axis. This must be submitted for any LiDAR TopDown annotation tasks, and defines the bounds to which the point cloud should be restricted to for annotation.
geometriesobjectrequired
This object is used to define which objects need to be annotated and which annotation geometries (box, polygon, line, point, cuboid, or ellipse) should be used for each annotation.
directed_linesarray of strings
List of labels under the “line” category in geometries that should have directionality. Note, the label names must be matched exactly.
annotation_attributesobject
This field is used to add additional attributes that you would like to capture per annotation. See Annotation Attributes for more details about annotation attributes.
linksobject
Use this field to define links between annotations. See Links for more details about links.
base_annotationsobject
Editable annotations, with the option to be 'locked', that a task should be initialized with. This is useful when you've run a model to prelabel the task and want annotators to refine those prelabels. Must contain the annotations field, which has the same format as the annotations field in the response.
groupsarray of strings
A list of groups that this label belongs to. If this choice has subchoices, those subchoices will also belong to these groups. This is used to provide additional info to each LabelDescription, as defined in LabelDescription nesting. Example: The label Single Solid belongs to groups Roundabout Edge and Colored Line, whereas the label Double Solid only belongs to the group Roundabout Edge.
rulesobject
Use this field to define relationships between annotations. If using line annotations to form polygon annotations, the labels of the involved annotations are set here.
disable_cuboid_projectionboolean
By default, when a LidarTopDown task is created as a dependent task of a LidarAnnotation task, the LidarAnnotation’s cuboids are projected as polygons in the LidarTopDown task. By setting this property to true, that behavior is disabled and no LidarAnnotation cuboids will be projected to the LidarTopDown Task. Note that this parameter only takes effect if the LidarTopdown task is a dependent task.
metadataobject
A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format. Max 10KB.
priorityinteger
A value of 10, 20, or 30 that defines the priority of a task within a project. The higher the number, the higher the priority.
unique_idstring
A arbitrary ID that you can assign to a task and then query for later. This ID must be unique across all projects under your account, otherwise the task submission will be rejected. See Avoiding Duplicate Tasks for more details.
clear_unique_id_on_errorboolean
If set to be true, if a task errors out after being submitted, the unique id on the task will be unset. This param allows workflows where you can re-submit the same unique id to recover from errors automatically
tagsarray of strings
Arbitrary labels that you can assign to a task. At most 5 tags are allowed per task. You can query tasks with specific tags through the task retrieval API.
lidar_taskstring
Task ID of a completed lidar task used to construct this Lidar TopDown task. Annotation information from the Lidar task will be used as a prior for the LTD task. This is only used when creating a Lidar TopDown task from a Lidar Cuboids Task
deviceHeightinteger
The height of the lidar device relative to the ground in meters. If a point on the ground has height z in the device coordinate frame, then z + deviceHeight should be about 0. Used to filter out points that are too high/low more accurately.
Request
import requests
url = "https://api.scale.com/v1/task/lidartopdown"
payload = {
"instruction": "**Instructions:** Please label all the things",
"callback_url": "https://example.com/callback",
"attachment": ["https://s3-us-west-1.amazonaws.com/scaleapi-cust-lidar/kitti-road-2011_10_03_drive_0047/frames/frame1.json"],
"attachments": ["https://s3-us-west-1.amazonaws.com/scaleapi-cust-lidar/kitti-road-2011_10_03_drive_0047/frames/frame1.json"],
"geometries": {
"newKey": "New Value",
"newKey-1": "New Value_1"
},
"priority": None
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "<YOUR_API_KEY>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Response
{
"callback_url": "http://www.example.com/callback",
"created_at": "2019-01-16T21:03:33.166Z",
"instruction": "**Instructions:** Please label all the things",
"is_test": false,
"params": {},
"status": "pending",
"task_id": "5a99e20de50d4979ce6d291e",
"type": "lidartopdown"
}
Change Dependent Task Options
This endpoint is used to change the options associated with dependent tasks. This can only be done if the original task is not complete, not just if dependent tasks have not been created.
POST this endpoint with a dependents object to update the dependent tasks options
Path Params
task_idstringrequired
Root task of the dependent tasks.
Body Params
defsarray of objects
Definitions of the tasks that will be created once this task is complete.
require_auditboolean
Whether or not to wait for a customer audit to fix/approve a task before creating the dependent tasks.
Request
import requests
url = "https://api.scale.com/v1/task/{task_id}/dependents/options"
payload = {
"defs": [
{
"labels": ["label1", "label2"],
"type": "lidarsegmentation",
"instruction": "**Instructions",
"callback_url": "http://www.example.com/callback",
"annotation_type": "imageannotation"
}
]
}
headers = {
"accept": "application/json",
"content-type": "application/json"
}
response = requests.post(url, headers=headers)
print(response.text)
Force Dependent Tasks Creation
This endpoint creates dependent tasks and skips the audit (assuming require_audit = true on a particular task). This will fail if the task is not completed, or dependent tasks have already been created.
Path Params
task_idstringrequired
Root task of the dependent tasks.
Request
import requests
url = "https://api.scale.com/v1/task/{task_id}/dependents/force_creation"
headers = {"accept": "application/json"}
response = requests.post(url, headers=headers)
print(response.text)