> ## Documentation Index
> Fetch the complete documentation index at: https://api-reference.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sensor Fusion / Lidar Tasks

> 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

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.

<ParamField path="Body Params" type="object">
  <ParamField path="project" type="string" required>
    The name of the project to associate this task with. See the [Projects](/docs/api-reference/projects) Section for more details.

    ***
  </ParamField>

  <ParamField path="batch" type="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](/docs/api-reference/batches) for more details.

    ***
  </ParamField>

  <ParamField path="instruction" type="string">
    A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to show example images, give structure to your instructions, and more. See our [instruction best practices](/docs/write-your-instructions) for more details.

    ***
  </ParamField>

  <ParamField path="callback_url" type="string">
    The full url (including the scheme `http://` or `https://`) of the callback when the task is completed. See the [Callback section](/docs/api-reference/callbacks) for more details about callbacks.

    ***
  </ParamField>

  <ParamField path="attachment" type="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`.

    ***
  </ParamField>

  <ParamField path="attachments" type="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](/docs/api-reference/callbacks), or protobuf files that encode `LidarFrame` messages as defined in the .proto file.

    ***
  </ParamField>

  <ParamField path="region_of_interest_2d" type="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.

    ***
  </ParamField>

  <ParamField path="region_of_interest_3d" type="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.

    ***
  </ParamField>

  <ParamField path="geometries" type="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

    ***
  </ParamField>

  <ParamField path="directed_lines" type="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.

    ***
  </ParamField>

  <ParamField path="annotation_attributes" type="object">
    This field is used to add additional attributes that you would like to capture per annotation. See [Annotation Attributes](/docs/api-reference/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.

    ***
  </ParamField>

  <ParamField path="links" type="object">
    Use this field to define links between annotations. See [Links](/docs/api-reference/annotation-attributes) for more details about links.

    If taxonomy service is enabled, this field will overwrite the links defined in the taxonomy version.

    ***
  </ParamField>

  <ParamField path="base_annotations" type="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.

    ***
  </ParamField>

  <ParamField path="groups" type="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](/docs/api-reference/annotation-attributes). 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.

    ***
  </ParamField>

  <ParamField path="rules" type="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.

    ***
  </ParamField>

  <ParamField path="disable_cuboid_projection" type="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.

    ***
  </ParamField>

  <ParamField path="metadata" type="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.

    ***
  </ParamField>

  <ParamField path="priority" type="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.

    ***
  </ParamField>

  <ParamField path="unique_id" type="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](/docs/api-reference/tasks) for more details.

    ***
  </ParamField>

  <ParamField path="clear_unique_id_on_error" type="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

    ***
  </ParamField>

  <ParamField path="tags" type="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.

    ***
  </ParamField>

  <ParamField path="lidar_task" type="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

    ***
  </ParamField>

  <ParamField path="deviceHeight" type="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.

    ***
  </ParamField>

  <ParamField path="taxonomy_srn" type="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
  </ParamField>
</ParamField>

```python theme={null}
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)

```

```json theme={null}
{
  "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](/docs/api-reference/callbacks)**. The `**attachments**` will be a list of links to external JSON files, each following the definition of a `**Frame**` as specified below.

<ParamField path="Body Params" type="object">
  <ParamField path="project" type="string">
    The name of the project to associate this task with. See the [Projects](/docs/api-reference/projects) Section for more details.

    ***
  </ParamField>

  <ParamField path="batch" type="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. For Scale Rapid projects specifying a batch is required. See [Batches section](/docs/api-reference/batches) for more details.

    ***
  </ParamField>

  <ParamField path="instruction" type="string">
    A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to show example images, give structure to your instructions, and more. See our [instruction best practices](/docs/rapid-or-how-it-works) for more details. For Scale Rapid projects, DO NOT set this field unless you specifically want to override the project level instructions.

    ***
  </ParamField>

  <ParamField path="callback_url" type="string">
    The full url (including the scheme `http://` or `https://`) of the callback when the task is completed. See the [Callback section](/docs/api-reference/callbacks) for more details about callbacks.

    ***
  </ParamField>

  <ParamField path="attachments" type="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](/docs/api-reference/callbacks), or protobuf files that encode `LidarFrame` messages as defined in the .proto file.

    ***
  </ParamField>

  <ParamField path="attachment_type" 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.

    ***
  </ParamField>

  <ParamField path="labels" type="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](/docs/api-reference/annotation-attributes) and Options for more details about label objects.

    ***
  </ParamField>

  <ParamField path="annotation_attributes" type="object">
    This field is used to add additional attributes that you would like to capture per annotation. See [Annotation Attributes](https://docs.scale.com/reference/attributes-overview) for more details about annotation attributes.

    ***
  </ParamField>

  <ParamField path="max_distance_meters" type="integer">
    The maximum distance in meters from the sensor for which an object should be labeled. If undefined, all visible objects will be labeled.

    ***
  </ParamField>

  <ParamField path="meters_per_unit" type="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.

    ***
  </ParamField>

  <ParamField path="frames_per_second" type="integer">
    The frequency of the frames per second.

    ***
  </ParamField>

  <ParamField path="labeling_sample_rate" type="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 `1`st, `k + 1`-th, `2k + 1`-th, ... , `floor((n - 1) / k) * k + 1`-th, and `n`th frames.

    ***
  </ParamField>

  <ParamField path="polygons_enabled" type="boolean">
    Enables polygon annotations, see the Polygons section in [Response on Callback](https://docs.scale.com/reference/lidar-callback-format#definition-polygon) for more details.

    ***
  </ParamField>

  <ParamField path="polygons_labels" type="array of strings">
    An array of strings describing the different types of polygons you'd like to be annotated in the scene.

    ***
  </ParamField>

  <ParamField path="metadata" type="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.

    ***
  </ParamField>

  <ParamField path="priority" type="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.

    ***
  </ParamField>

  <ParamField path="unique_id" type="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](/docs/api-reference/tasks)[ ](/docs/api-reference/tasks)for more details.

    ***
  </ParamField>

  <ParamField path="clear_unique_id_on_error" type="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

    ***
  </ParamField>

  <ParamField path="tags" type="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.

    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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 task
  ```
</CodeGroup>

```json theme={null}
{
  "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](/docs/api-reference/sensor-fusion-lidar-tasks)**.\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](/docs/api-reference/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](/docs/api-reference/labels)**. 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](/docs/api-reference/sensor-fusion-lidar-reference#definition-frame)**.

You should provide additional **[markdown-enabled](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)** 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**`

<ParamField path="Body Params" type="object">
  <ParamField path="project" type="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. For Scale Rapid projects specifying a batch is required. See Batches section for more details.

    ***
  </ParamField>

  <ParamField path="batch" type="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. For Scale Rapid projects specifying a batch is required. See Batches section for more details.

    ***
  </ParamField>

  <ParamField path="instruction" type="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 instruction

    ***
  </ParamField>

  <ParamField path="callback_url" type="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.

    ***
  </ParamField>

  <ParamField path="attachments" type="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.

    ***
  </ParamField>

  <ParamField path="attachment_type" 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.

    ***
  </ParamField>

  <ParamField path="labels" type="array 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.

    ***
  </ParamField>

  <ParamField path="metadata" type="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.

    ***
  </ParamField>

  <ParamField path="priority" type="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.

    ***
  </ParamField>

  <ParamField path="unique_id" type="object">
    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](/docs/api-reference/data-engine-reference#avoiding-duplicate-tasks)** for more details

    ***
  </ParamField>

  <ParamField path="clear_unique_id_on_error" type="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

    ***
  </ParamField>

  <ParamField path="tags" type="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.

    ***
  </ParamField>
</ParamField>

```python theme={null}
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)

```

```json theme={null}
{
  "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.

<ParamField path="Body Params" type="object">
  <ParamField path="project" type="string">
    The name of the [project](/docs/api-reference/projects) to associate this task with.

    ***
  </ParamField>

  <ParamField path="batch" type="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. For Scale Rapid projects specifying a batch is required. See **[Batches section](/docs/api-reference/batches)** for more details.

    ***
  </ParamField>

  <ParamField path="instruction" type="string">
    A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to show example images, give structure to your instructions, and more. See our [instruction best practices](/docs/write-your-instructions) for more details. For Scale Rapid projects, DO NOT set this field unless you specifically want to override the project level instructions.

    ***
  </ParamField>

  <ParamField path="callback_url" type="string">
    The full url (including the scheme `http://` or `https://`) or email address of the [callback](/docs/api-reference/callbacks) that will be used when the task is completed.

    ***
  </ParamField>

  <ParamField path="annotation_type" type="string" required>
    The 2D annotation type to return, either `imageannotation` (preferred), `annotation`, `cuboidannotation`, or `polygonannotation`

    ***
  </ParamField>

  <ParamField path="lidar_task" type="string" required>
    The ID of the completed lidar task to request corrected 2D projections for.

    ***
  </ParamField>

  <ParamField path="annotation_attributes" type="object">
    This field is used to add additional attributes that you would like to capture per annotation. See [Annotation Attributes](/docs/api-reference/annotation-attributes) for more details about annotation attributes.

    ***
  </ParamField>

  <ParamField path="camera_ids" type="array of integers">
    Indices of the CameraImages in the `lidarannotation` task to request corrected 2D projections for. Defaults to all cameras.

    ***
  </ParamField>

  <ParamField path="events_to_annotate" type="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)

    ***
  </ParamField>

  <ParamField path="event_camera_ids" type="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

    ***
  </ParamField>

  <ParamField path="can_add_annotations" type="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.

    ***
  </ParamField>

  <ParamField path="can_edit_annotations" type="boolean">
    Whether or not to allow labelers to modify any aspect of an annotation (labels, attributes and position). True by default.

    ***
  </ParamField>

  <ParamField path="can_edit_annotation_positions" type="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.

    ***
  </ParamField>

  <ParamField path="can_delete_annotations" type="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.

    ***
  </ParamField>

  <ParamField path="labeling_sample_rate" type="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 `1`st, `k + 1`-th, `2k + 1`-th, ... , `floor((n - 1) / k) * k + 1`-th, and `n`th 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].

    ***
  </ParamField>

  <ParamField path="additional_labels" type="array of strings">
    An array of strings or [LabelDescription](/docs/api-reference/annotation-attributes) 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.

    ***
  </ParamField>

  <ParamField path="skip_labels" type="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.

    ***
  </ParamField>

  <ParamField path="geometries" type="boolean">
    (required if `annotation_type=imageannotation`).<br />An object mapping `box`, `polygon`, `line`, `point`, `cuboid`, or `ellipse`to Geometry objects, indicating the geometry with which annotations should be drawn and the geometry of generated projections.

    ***
  </ParamField>

  <ParamField path="default_geometry" type="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`.

    ***
  </ParamField>

  <ParamField path="copy_all_lidar_task_attributes" type="boolean">
    If set, all attributes from the `lidar_task` will be copied to the linking task -- see [Inherited Lidar Attributes](/docs/api-reference/annotation-attributes)[ ](/docs/api-reference/annotation-attributes)for details.

    ***
  </ParamField>

  <ParamField path="padding" type="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.

    ***
  </ParamField>

  <ParamField path="paddingX" type="integer">
    The amount of padding in pixels added to the left and right of each video frame. Overrides `padding` if set. `0` by default.

    ***
  </ParamField>

  <ParamField path="paddingY" type="integer">
    The amount of padding in pixels added to the top and bottom of each video frame. Overrides `padding` if set. `0` by default.

    ***
  </ParamField>

  <ParamField path="layers" type="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`](/docs/api-reference/sensor-fusion-lidar-reference), one for each frame of the `lidarlinking` task. See [example file](https://scale-static-assets.s3-us-west-2.amazonaws.com/uploads/lidarLinkingLayers0.json) 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.

    ***
  </ParamField>

  <ParamField path="metadata" type="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.

    ***
  </ParamField>

  <ParamField path="priority" type="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.

    ***
  </ParamField>

  <ParamField path="unique_id" type="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](/docs/api-reference/tasks) for more details.

    ***
  </ParamField>

  <ParamField path="clear_unique_id_on_error" type="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

    ***
  </ParamField>

  <ParamField path="tags" type="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.

    ***
  </ParamField>
</ParamField>

```python theme={null}
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)

```

```json theme={null}
{
  "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

<ParamField path="Path Params" type="object">
  <ParamField path="task_id" type="string" required>
    Root task of the dependent tasks.

    ***
  </ParamField>
</ParamField>

<ParamField path="Body Params" type="object">
  <ParamField path="defs" type="array of objects">
    Definitions of the tasks that will be created once this task is complete.

    ***
  </ParamField>

  <ParamField path="require_audit" type="boolean">
    Whether or not to wait for a customer audit to fix/approve a task before creating the dependent tasks.

    ***
  </ParamField>
</ParamField>

```python theme={null}
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.

<ParamField path="Path Params" type="object">
  <ParamField path="task_id" type="string" required>
    Root task of the dependent tasks.

    ***
  </ParamField>
</ParamField>

```python theme={null}
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)

```