9.2 KiB
Task
Example task:
{
"id": 134,
"project": 27,
"processing_node": 10,
"images_count": 48,
"available_assets": [
"all.zip",
"orthophoto.tif",
"orthophoto.png",
"georeferenced_model.las",
"georeferenced_model.ply",
"georeferenced_model.csv",
"textured_model.zip"
],
"uuid": "4338d684-91b4-49a2-b907-8ba171894393",
"name": "Task Name",
"processing_time": 2197417,
"auto_processing_node": false,
"status": 40,
"last_error": null,
"options": [
{
"name": "use-opensfm-pointcloud",
"value": true
}
],
"ground_control_points": null,
"created_at": "2017-02-18T18:01:55.402551Z",
"pending_action": null
}
A Task is the basic processing unit of WebODM. To compute an orthophoto, point cloud and textured model from a set of images, you need to create a Task.
Field | Type | Description |
---|---|---|
id | int | Unique identifier |
project | int | Project ID the task belongs to |
processing_node | int | The ID of the Processing Node this task has been assigned to, or null if no Processing Node has been assigned. |
images_count | int | Number of images |
available_assets | string[] | List of assets available for download |
uuid | string | Unique identifier assigned by a Processing Node once processing has started. |
name | string | User defined name for the task |
processing_time | int | Milliseconds that have elapsed since the start of processing, or -1 if no information is available. Useful for displaying a time status report to the user. |
auto_processing_node | boolean | Whether WebODM should automatically assign the next available Processing Node to process this Task. A user can set this to false to manually choose a Processing Node. |
status | int | One of Status Codes, or null if no status is available. |
last_error | string | The last error message reported by a Processing Node in case of processing failure. |
options | JSON[] | JSON-encoded list of name/value pairs, where each pair represents a command line option to be passed to a Processing Node. |
ground_control_points | string | Currently unused. See #37 |
created_at | string | Creation date and time |
pending_action | int | One of Pending Actions, or null if no pending action is set. |
Create a task
POST /api/projects/{project_id}/tasks/
Parameter | Required | Default | Description |
---|---|---|---|
images[] | * | "" | List of multipart-encoded images (2 minimum) |
processing_node | null | The ID of the Processing Node this Task should be assigned to. If not specified, and auto_processing_node is true , a Processing Node will be automatically assigned. |
|
name | "" | User defined name for the task | |
auto_processing_node | true | Whether WebODM should automatically assign the next available Processing Node to process this Task. | |
options | "[]" | JSON-encoded list of name/value pairs, where each pair represents a command line option to be passed to a Processing Node. |
You assign a Task to a Project by passing the proper project_id
path in the URL.
Update a task
PATCH /api/projects/{project_id}/tasks/{task_id}/
Parameters are the same as above.
Delete a task
DELETE /api/projects/{project_id}/tasks/{task_id}/
Upon deletion, all images and assets associated with the Task are deleted also. The operation is irreversible.
Get list of tasks
Task list:
[
{
"id": 6,
"project": 2,
"processing_node": 2,
"images_count": 89,
"uuid": "2e8b687d-c269-4e2f-91b3-5a2cd51b5321",
"name": "Test name",
"processing_time": 8402184,
"auto_processing_node": true,
"status": 40,
"last_error": null,
"options": [],
"ground_control_points": null,
"created_at": "2016-12-08T13:32:28.139474Z",
"pending_action": null
}
]
GET /api/projects/{project_id}/tasks/
Retrieves all Task items associated with project_id
.
Download assets
GET /api/projects/{project_id}/tasks/{task_id}/download/{asset}
After a task has been successfully processed, the user can download several assets from this URL. Not all assets are always available. For example if GPS information is missing from the input images, the orthophoto.tif
asset will be missing. You can check the available_assets
property of a Task to see which assets are available for download.
Asset | Description |
---|---|
all.zip | Archive (.zip) containing all assets, including an orthophoto, TMS tiles, a textured 3D model and point cloud in various formats. |
orthophoto.tif | GeoTIFF orthophoto. |
orthophoto.png | PNG orthophoto. |
textured_model.zip | Archive containing the textured 3D model |
georeferenced_model.las | Point cloud in .LAS format. |
georeferenced_model.ply | Point cloud in .PLY format. |
georeferenced_model.csv | Point cloud in .CSV format. |
Download assets (raw path)
GET /api/projects/{project_id}/tasks/{task_id}/assets/{path}/
After a task has been successfully processed, its assets are stored in a directory on the file system. This API call allows direct access to the files in that directory (by default: WebODM/app/media/project/{project_id}/task/{task_id}/assets
). This can be useful to those applications that want to stream a Potree
dataset, or render a textured 3D model on the fly.
Retrieve console output
Console output example:
curl -H "Authorization: JWT <your_token>" http://localhost:8000/api/projects/2/tasks/1/output/?line=5
[DEBUG] /var/www/data/e453747f-5fd4-4654-9622-b02727b29fc5/images\n[DEBUG] Loaded DJI_0219.JPG | camera: dji fc300s ...
GET /api/projects/{project_id}/tasks/{task_id}/output/
As a Task is being processed, processing nodes will return an output string that can be used for debugging and informative purposes. Output is only available after processing has started.
Parameter | Required | Default | Description |
---|---|---|---|
line | 0 | Only display the output starting from a certain line number. This can be useful to display output in realtime to the user by keeping track of the number of lines that have been displayed to the user so far and thus avoiding to download all output at every request. |
Cancel task
POST /api/projects/{project_id}/tasks/{task_id}/cancel/
Stop processing a Task. Canceled tasks can be restarted.
Remove task
POST /api/projects/{project_id}/tasks/{task_id}/remove/
All assets associated with it will be destroyed also. If the Task is currently being processed, processing will stop.
Restart task
POST /api/projects/{project_id}/tasks/{task_id}/restart/
If a Task has been canceled or has failed processing, or has completed but the user decided to change processing options, it can be restarted. If the Processing Node assigned to the Task has not changed, processing will happen more quickly compared to creating a new Task, since the Processing Node remembers the uuid
of the Task and will attempt to reuse previous results from the computation pipeline.
Orthophoto TMS layer
GET /api/projects/{project_id}/tasks/{task_id}/tiles.json
GET /api/projects/{project_id}/tasks/{task_id}/tiles/{Z}/{X}/{Y}.png
After a task has been successfully processed, a TMS layer is made available for inclusion in programs such as Leaflet or Cesium.
Pending Actions
In some circumstances, a Task can have a pending action that requires some amount of time to be performed.
Pending Action | Code | Description |
---|---|---|
CANCEL | 1 | Task is being canceled |
REMOVE | 2 | Task is being removed |
RESTART | 3 | Task is being restarted |
Status Codes
Status | Code | Description |
---|---|---|
QUEUED | 10 | Task's files have been uploaded to a Processing Node and are waiting to be processed. |
RUNNING | 20 | Task is currently being processed. |
FAILED | 30 | Task has failed for some reason (not enough images, out of memory, Piero forgot to close a parenthesis, etc.) |
COMPLETED | 40 | Task has completed. Assets are be ready to be downloaded. |
CANCELED | 50 | Task was manually canceled by the user. |