Documentation | Refonte

Introduction to Refonte.AI API

Introduction to Refonte.AI API Authentication Callbacks Secure Results URLs Errors

Data Engine Core Resources

Data Engine Tasks Types

Create Lidar Topdown Tasks

This endpoint generates a lidartopdown task that allows you to annotate a group of lidar Frames with vector geometric forms in a top-down manner. Three geometries are available: polygon, line, and point.

Using the provided geometries, Fonte will annotate the top-down photos given a set of LiDAR Frames and optional camera data. More information on the callback_url, which is the URL that will be POSTed upon task completion, may be found in the Callback section. A collection of links to external JSON files, each containing a frame specification, will be included in the attachments.

Body Params

project string required

The name of the project to associate this task with.

batch string required

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.

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

attachment array of strings required

necessary if the attachments are not mentioned. the complete image url (png, jpg) to be used as the TopDown aerial imagery for a task that needs to be categorized. The attachments fields should be empty if an attachment is submitted, and vice versa. Projecting the points in the set of attachments will automatically create an attachment if the work is a LiDAR task rather than an aerial image task.

attachments array of strings required

A list of the URLs corresponding to the Frame objects that you want labeled. Time order for the frames should be followed naturally. The URLs have to point to Callback section, JSON files that adhere to the aforementioned specification, or protobuf files that encapsulate LidarFrame messages as specified in the.proto file.

region_of_interest_2d object

required for aerial imaging jobs when submitting type world_camera. Refonte is able to convert lon/lat world coordinates to pixels correctly thanks to this object. It enables Refonte.Ai to determine the camera location's pixel coordinates on the given aerial imaging task. The camera context images won't render on the task if this isn't supplied.

region_of_interest_3d object

required for lidar activities. This object rotates counterclockwise to the z-axis, cropping the attachments' points to a rectangle on the XY plane centered around the position. This outlines the parameters within which the point cloud should be limited for annotation and is required for all LiDAR TopDown annotation activities.

geometries object required

The annotation requirements for an object and the annotation geometries (box, polygon, line, and poin) that should be applied to each annotation are specified by this object. This field will replace the geometries specified in the taxonomy version if the taxonomy service is enabled. necessary if taxonomy services are not used

directed_line 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

You can add other attributes here that you would like to record for each annotation. For additional information regarding annotation attributes, see Annotation Attributes. This field will replace the annotation attributes specified in the taxonomy version if the taxonomy service is enabled.

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 the groups to which this label is assigned. Subchoices that are part of this choice will also fall into these categories. As stated in LabelDescription nesting, this is used to add more information to each LabelDescription. As an illustration, the label Double Solid is exclusive to the group Roundabout Edge, while the label Single Solid is a part of both the Colored Line and Roundabout Edge groups.

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

The cuboids of the LidarAnnotation task are projected as polygons in the LidarTopDown task by default when the LidarTopDown task is formed as a dependent task of the LidarAnnotation task. This behavior can be turned off and no LidarAnnotation cuboids will be projected to the LidarTopDown Task by setting this attribute to true. Keep in mind that the LidarTopdown task must be a dependent task for this parameter to be active.

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.

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 meters-based height of the lidar device above the ground. Z + deviceHeight should be close to 0 if a ground point's height in the device coordinate frame is z. used to more precisely filter out spots that are excessively high or low.

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.

Request

Python

POST  /v1/task/lidartopdown

import requests

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

# Define the URL for the API endpoint
url = "https://api.refonte.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://refonteapi-cust-lidar/frame1.json"],
    "attachments": ["https://refonteapi-cust-lidar/frame1.json"],
    "geometries": {
        "newKey": "New Value",
        "newKey-1": "New Value_1"
    },
    "priority": None
}

# Set up the headers for the request
headers = {
    "accept": "application/json",      
    "content-type": "application/json"
}

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

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

Create Lidar Cuboid Annotation

The lidarannotation task is created by this endpoint. In this work, one of our Refonters views the outputs from a sequence of LIDAR frames plus, if available, radar and camera data. It then uses 3D cuboids to annotate the locations of various objects in the 3D world. The parameters attachments, labels, and attachment_type are necessary for this activity.

More information on the callback_url, which is the URL that will be POSTed upon task completion, may be found in the Callback section. Each attachment will have a list of links to external JSON files that each meet the guidelines below for defining a frame.

Body Params

project string

The name of the project to associate this task with.

batch string

The batch name that this job should be associated with. It should be noted that if a batch is supplied, the task will be automatically connected with the batch's project; thus, there is no need to mention the project. It is necessary to define a batch for Refonte Rapid projects. For more information, see the Batches section.

instruction string

The instructions can be found in an iframe embedded Google Doc or a markdown-enabled string. Markdown can be used to display sample images, organize your instructions, and much more. For further information, see our best practices for instruction. Regarding Fonte For quick projects, unless you specifically want to override the project level instructions, DO NOT set this field.

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

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 string 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 objects

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.

Request

Python

POST  /v1/task/lidarannotation

import requests

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

# Define the URL for the API endpoint
url = "https://api.refonte.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://refonteapi-cust-lidar/frame1.json"],
    "attachment_type": "json",
    "labels": ["Vehicle"],
    "priority": None
}

# Set up the headers for the request
headers = {
    "accept": "application/json", 
    "content-type": "application/json"
}

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

Response

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

A lidarsegmentation task is created by this endpoint. One of our Taskers examines the outputs from a sequence of LIDAR frames in this work, together with optional camera data, and annotates the locations of various objects in the 3D space by giving each LidarPoint a class. This kind of task can be made independently, or it can be made in response to an existing Lidar Annotation task that has been finished.

For this task, labels, attachments, and attachment_type are necessary parameters. More information about the callback_url, which is the URL that will be POSTed upon task completion, can be found in the callbacks section.

The labels array lists the object classes for which semantic information is desired. Instance labels are supported, by specifying instance_label: true when defining the label. For example, ['Road', ['choice': 'Pedestrian', 'instance_label': true]]. 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']]] . The attachments will be a list of links to external JSON files, each following the definition of a Frame.

You should use the instruction argument to supply more markdown-enabled instructions.It is highly advised that you include numerous examples of jobs completed both correctly and badly in your Markdown instructions. If everything goes well, refonte will return the produced task object right away; you should save the task_id at the very least.

Body Params

project string

The name of the project to associate this task with.

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. For Refonte Rapid projects specifying a batch is required. See Batches section for more details.

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 refonte 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 string 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 string 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.

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.

Request

Python

POST  /v1/task/lidarsegmentation

import requests

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

# Define the URL for the API endpoint
url = "https://api.refonte.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://refonteapi-cust-lidar/frames/frame1.json"],
    "attachment_type": "json",
    "labels": ["Vegetation"],
    "priority": None
}

# Set up the headers for the request
headers = {
    "accept": "application/json",  
    "content-type": "application/json" 
}

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

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

A lidarlinking job is created by this endpoint. Even if the 3D cuboids are accurate, there are situations when improper camera calibrations in 3D activities cause the cuboid vertices to be incorrectly projected onto 2D images. Users can request corrected 2D projections, each identified with the same ID as the corresponding 3D cuboid, through the 2D/3D linkage API.

This task requires the following parameters: lidar_task, annotation_type, and instruction. The ID of the finished lidar work to request updated 2D projections is lidar_task. Annotation_type: This specifies the 2D annotation type—image annotation, which is the recommended option—to return, along with annotation, cuboidannotation, and polygonannotation. More information on the format of these annotation types can be found in the corresponding documentation for boxes, cuboids, polygons, and images.

Additional markdown-enabled instructions must be supplied using the instruction option. It is highly advised that you include numerous examples of jobs completed both correctly and badly in your Markdown instructions. Refonte will return the produced task object right away if it is successful; you should save the task_id at the very least. Following the completion of a lidarsegmentation or lidarannotation job, lidarlinking tasks can also be generated automatically. See Dependent Tasks to find out more about this.

Body Params

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://) of the callback when the task is completed. See the Callback section for more details about callbacks.

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 string

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 string

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

Request

Python

POST  /v1/task/lidarlinking

import requests

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

# Define the URL for the API endpoint
url = "https://api.refonte.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",     
    "content-type": "application/json"
}

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

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

Change Dependent Task Options

To modify the settings related to dependent tasks, use this endpoint. This can only be carried out in the event that the primary work remains unfinished, not merely in the absence of dependent chores.

To update the dependent tasks parameters, POST this endpoint with a dependents object.

Path Params

task_id string required

Root task of the dependent tasks.

Body Params

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.

Request

Python

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.refonte.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",    
    "content-type": "application/json" 
}

# 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, presuming require_audit = true on a given job, generates dependent tasks and bypasses the audit. If the job is not finished or if dependent tasks have already been created, this will fail.

Path Params

task_id string required

Root task of the dependent tasks.

Request

Python

POST  /v1/task/{task_id}/dependents/force_creation


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.refonte.com/v1/task/{TASK_ID}/dependents/force_creation"

# Set up the headers for the request
headers = {
    "accept": "application/json",    
    "content-type": "application/json" 
}

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

Updated about 2 months ago