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

object

project

string

required

The name of the project to associate this task with. See the Projects Section for more details.

batch

string

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.

instruction

string

callback_url

string

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.

attachment

array of strings

required

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.

attachments

array of strings

required

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_2d

object

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_3d

object

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.

geometries

object

required

This object is used to define which objects need to be annotated and which annotation geometries (box, polygon, line, poin) should be used for each annotation.If taxonomy service is enabled, this field will overwrite the geometries defined in the taxonomy version.Required if not using taxonomy service

directed_lines

array of strings

List of labels under the “line” category in geometries that should have directionality. Note, the label names must be matched exactly.If taxonomy service is enabled, this field will overwrite the directed lines defined in the taxonomy version.

annotation_attributes

object

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.If taxonomy service is enabled, this field will overwrite the annotation attributes defined in the taxonomy version.

links

object

Use this field to define links between annotations. See Links for more details about links.If taxonomy service is enabled, this field will overwrite the links defined in the taxonomy version.

base_annotations

object

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.

groups

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

rules

object

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_projection

boolean

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.

metadata

object

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.

priority

integer

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_id

string

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_error

boolean

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

tags

array 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_task

string

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

deviceHeight

integer

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.

taxonomy_srn

string

Use this field to specify a taxonomy version to use from the taxonomy service when it is enabled. If this field is empty, the task will use the most recently submitted taxonomy

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/task/lidartopdown"

# Define the payload for the LIDAR top-down task
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
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

{
  "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"
}

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

object

project

string

The name of the project to associate this task with. See the Projects Section for more details.

batch

string

instruction

string

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_url

string

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.

attachments

array of strings

required

attachment_type

string

required

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.

labels

array of strings

required

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_attributes

object

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_meters

integer

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_unit

integer

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_second

integer

The frequency of the frames per second.

labeling_sample_rate

integer

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_enabled

boolean

Enables polygon annotations, see the Polygons section in Response on Callback for more details.

polygons_labels

array of strings

An array of strings describing the different types of polygons you’d like to be annotated in the scene.

metadata

object

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.

priority

integer

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_id

string

clear_unique_id_on_error

boolean

tags

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

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/task/lidarannotation"

# Define the payload for the LIDAR annotation task
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
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

{
  "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](/docs/api-reference/sensor-fusion-lidar-reference#definition-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

object

project

string

batch

string

instruction

string

callback_url

string

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.

attachments

array 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_type

string

required

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.

labels

array of strings

metadata

object

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.

priority

integer

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_id

object

clear_unique_id_on_error

boolean

tags

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

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/task/lidarsegmentation"

# Define the payload for the LIDAR segmentation task
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
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

{
  "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

object

project

string

The name of the project to associate this task with.

batch

string

instruction

string

callback_url

string

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_type

string

required

The 2D annotation type to return, either imageannotation (preferred), annotation, cuboidannotation, or polygonannotation

lidar_task

string

required

The ID of the completed lidar task to request corrected 2D projections for.

annotation_attributes

object

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_ids

array of integers

Indices of the CameraImages in the lidarannotation task to request corrected 2D projections for. Defaults to all cameras.

events_to_annotate

array 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_ids

array 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_annotations

boolean

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_annotations

boolean

Whether or not to allow labelers to modify any aspect of an annotation (labels, attributes and position). True by default.

can_edit_annotation_positions

boolean

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_annotations

boolean

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_rate

integer

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_labels

array 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_labels

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

geometries

boolean

(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_geometry

string

(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_attributes

boolean

If set, all attributes from the lidar_task will be copied to the linking task — see Inherited Lidar Attributes for details.

padding

integer

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.

paddingX

integer

The amount of padding in pixels added to the left and right of each video frame. Overrides padding if set. 0 by default.

paddingY

integer

The amount of padding in pixels added to the top and bottom of each video frame. Overrides padding if set. 0 by default.

layers

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

metadata

object

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.

priority

integer

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_id

string

clear_unique_id_on_error

boolean

tags

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

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/task/lidarlinking"

# Define the payload for the LIDAR linking task
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"
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

{
  "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"
  }
}

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

object

task_id

string

required

Root task of the dependent tasks.

Body Params

object

defs

array of objects

Definitions of the tasks that will be created once this task is complete.

require_audit

boolean

Whether or not to wait for a customer audit to fix/approve a task before creating the dependent tasks.

import requests

# Replace with your actual API key and task ID
API_KEY = 'your_api_key_here'
TASK_ID = 'your_task_id_here'

# Define the URL for the API endpoint
url = f"https://api.scale.com/v1/task/{TASK_ID}/dependents/options"

# Define the payload for the dependent task options
payload = { 
    "defs": [
        {
            "labels": ["label1", "label2"],
            "type": "lidarsegmentation",
            "instruction": "**Instructions",
            "callback_url": "http://www.example.com/callback",
            "annotation_type": "imageannotation"
        }
    ] 
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
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

object

task_id

string

required

Root task of the dependent tasks.

import requests

# Replace with your actual API key and task ID
API_KEY = 'your_api_key_here'
TASK_ID = 'your_task_id_here'

# Define the URL for the API endpoint
url = f"https://api.scale.com/v1/task/{TASK_ID}/dependents/force_creation"

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request using the 'auth' parameter
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Documentation Index

​Create Lidar Topdown Tasks

​Create Lidar Cuboid Annotation

​Create Lidar Segmentation Annotation

​Create Lidar Linking Annotation

​Change Dependent Task Options

​Force Dependent Tasks Creation

Create Lidar Topdown Tasks

Create Lidar Cuboid Annotation

Create Lidar Segmentation Annotation

Create Lidar Linking Annotation

Change Dependent Task Options

Force Dependent Tasks Creation