index.adoc

NodeODM

Overview

REST API to access ODM

Version information

Version : 2.2.1

Contact information

Contact : Piero Toffanin

License information

License : AGPL-3.0

URI scheme

BasePath : /
Schemes : HTTP

Consumes

• application/json

Produces

• application/json

• application/zip

Paths

GET /auth/info

Description

Retrieves login information for this node.

Responses

HTTP Code	Description	Schema
200	LoginInformation	Response 200

Response 200

Name	Description	Schema
loginUrl required	URL (absolute or relative) where to make a POST request to obtain a token, or null if login is disabled.	string
message required	Message to be displayed to the user prior to login/registration. This might include instructions on how to register or login, or to communicate that authentication is not available.	string
registerUrl required	URL (absolute or relative) where to make a POST request to register a user, or null if registration is disabled.	string

Tags

• auth

POST /auth/login

Description

Retrieve a token from a username/password pair.

Parameters

Type	Name	Description	Schema	Default
Body	password required	Password	string
Body	username required	Username	string

Responses

HTTP Code	Description	Schema
200	Login Succeeded	Response 200
default	Error	Error

Response 200

Name	Description	Schema
token required	Token to be passed as a query parameter to other API calls.	string

POST /auth/register

Description

Register a new username/password.

Parameters

Type	Name	Description	Schema	Default
Body	password required	Password	string
Body	username required	Username	string

Responses

HTTP Code	Description	Schema
200	Response	Response

GET /info

Description

Retrieves information about this node

Parameters

Type	Name	Description	Schema	Default
Query	token optional	Token required for authentication (when authentication is required).	string

Responses

HTTP Code	Description	Schema
200	Info	Response 200

Response 200

Name	Description	Schema
availableMemory optional	Amount of RAM available in bytes	integer
cpuCores optional	Number of CPU cores (virtual)	integer
engine required	Lowercase identifier of processing engine	string
engineVersion required	Current version of processing engine	string
maxImages required	Maximum number of images allowed for new tasks or null if there’s no limit.	integer
maxParallelTasks optional	Maximum number of tasks that can be processed simultaneously	integer
taskQueueCount required	Number of tasks currently being processed or waiting to be processed	integer
totalMemory optional	Amount of total RAM in the system in bytes	integer
version required	Current API version	string

Tags

• server

GET /options

Description

Retrieves the command line options that can be passed to process a task

Parameters

Type	Name	Description	Schema	Default
Query	token optional	Token required for authentication (when authentication is required).	string

Responses

HTTP Code	Description	Schema
200	Options	< Option > array

Option

Name	Description	Schema
domain required	Valid range of values (for example, "positive integer" or "float > 0.0")	string
help required	Description of what this option does	string
name required	Command line option (exactly as it is passed to the OpenDroneMap process, minus the leading '–')	string
type required	Datatype of the value of this option	enum (int, float, string, bool)
value required	Default value of this option	string

Tags

• server

POST /task/cancel

Description

Cancels a task (stops its execution, or prevents it from being executed)

Parameters

Type	Name	Description	Schema	Default
Query	token optional	Token required for authentication (when authentication is required).	string
Body	uuid required	UUID of the task	string

Responses

HTTP Code	Description	Schema
200	Command Received	Response

GET /task/list

Description

Gets the list of tasks available on this node.

Parameters

Type	Name	Description	Schema	Default
Query	token optional	Token required for authentication (when authentication is required).	string

Responses

HTTP Code	Description	Schema
200	Task List	< Response 200 > array
default	Error	Error

Response 200

Name	Description	Schema
uuid required	UUID	string

Tags

• task

POST /task/new

Description

Creates a new task and places it at the end of the processing queue. For uploading really large tasks, see /task/new/init instead.

Parameters

Type	Name	Description	Schema	Default
Header	set-uuid optional	An optional UUID string that will be used as UUID for this task instead of generating a random one.	string
Query	token optional	Token required for authentication (when authentication is required).	string
FormData	dateCreated optional	An optional timestamp overriding the default creation date of the task.	integer
FormData	images optional	Images to process, plus optional files such as a GEO file (geo.txt), image groups file (image_groups.txt), GCP file (*.txt), seed file (seed.zip) or alignment files (align.las, align.laz, align.tif). If included, the GCP file should have .txt extension. If included, the seed archive pre-polulates the task directory with its contents.	file
FormData	name optional	An optional name to be associated with the task	string
FormData	options optional	Serialized JSON string of the options to use for processing, as an array of the format: [{name: option1, value: value1}, {name: option2, value: value2}, …]. For example, [{"name":"cmvs-maxImages","value":"500"},{"name":"time","value":true}]. For a list of all options, call /options	string
FormData	outputs optional	An optional serialized JSON string of paths relative to the project directory that should be included in the all.zip result file, overriding the default behavior.	string
FormData	skipPostProcessing optional	When set, skips generation of point cloud tiles.	boolean
FormData	webhook optional	Optional URL to call when processing has ended (either successfully or unsuccessfully).	string
FormData	zipurl optional	URL of the zip file containing the images to process, plus an optional GEO file and/or an optional GCP file. If included, the GCP file should have .txt extension	string

Responses

HTTP Code	Description	Schema
200	Success	Response 200
default	Error	Error

Response 200

Name	Description	Schema
uuid required	UUID of the newly created task	string

Consumes

• multipart/form-data

Tags

• task

POST /task/new/commit/{uuid}

Description

Creates a new task for which images have been uploaded via /task/new/upload.

Parameters

Type	Name	Description	Schema	Default
Path	uuid required	UUID of the task	string
Query	token optional	Token required for authentication (when authentication is required).	string

Responses

HTTP Code	Description	Schema
200	Success	Response 200
default	Error	Error

Response 200

Name	Description	Schema
uuid required	UUID of the newly created task	string

Tags

• task

POST /task/new/init

Description

Initialize the upload of a new task. If successful, a user can start uploading files via /task/new/upload. The task will not start until /task/new/commit is called.

Parameters

Type	Name	Description	Schema	Default
Header	set-uuid optional	An optional UUID string that will be used as UUID for this task instead of generating a random one.	string
Query	token optional	Token required for authentication (when authentication is required).	string
FormData	dateCreated optional	An optional timestamp overriding the default creation date of the task.	integer
FormData	name optional	An optional name to be associated with the task	string
FormData	options optional	Serialized JSON string of the options to use for processing, as an array of the format: [{name: option1, value: value1}, {name: option2, value: value2}, …]. For example, [{"name":"cmvs-maxImages","value":"500"},{"name":"time","value":true}]. For a list of all options, call /options	string
FormData	outputs optional	An optional serialized JSON string of paths relative to the project directory that should be included in the all.zip result file, overriding the default behavior.	string
FormData	skipPostProcessing optional	When set, skips generation of point cloud tiles.	boolean
FormData	webhook optional	Optional URL to call when processing has ended (either successfully or unsuccessfully).	string

Responses

HTTP Code	Description	Schema
200	Success	Response 200
default	Error	Error

Response 200

Name	Description	Schema
uuid required	UUID of the newly created task	string

Tags

• task

POST /task/new/upload/{uuid}

Description

Adds one or more files to the task created via /task/new/init. It does not start the task. To start the task, call /task/new/commit.

Parameters

Type	Name	Description	Schema	Default
Path	uuid required	UUID of the task	string
Query	token optional	Token required for authentication (when authentication is required).	string
FormData	images required	Images to process, plus optional files such as a GEO file (geo.txt), image groups file (image_groups.txt), GCP file (*.txt), seed file (seed.zip) or alignment files (align.las, align.laz, align.tif). If included, the GCP file should have .txt extension. If included, the seed archive pre-polulates the task directory with its contents.	file

Responses

HTTP Code	Description	Schema
200	File Received	Response
default	Error	Error

Consumes

• multipart/form-data

Tags

• task

POST /task/remove

Description

Removes a task and deletes all of its assets

Parameters

Type	Name	Description	Schema	Default
Query	token optional	Token required for authentication (when authentication is required).	string
Body	uuid required	UUID of the task	string

Responses

HTTP Code	Description	Schema
200	Command Received	Response

POST /task/restart

Description

Restarts a task that was previously canceled, that had failed to process or that successfully completed

Parameters

Type	Name	Description	Schema	Default
Query	token optional	Token required for authentication (when authentication is required).	string
Body	options optional	Serialized JSON string of the options to use for processing, as an array of the format: [{name: option1, value: value1}, {name: option2, value: value2}, …]. For example, [{"name":"cmvs-maxImages","value":"500"},{"name":"time","value":true}]. For a list of all options, call /options. Overrides the previous options set for this task.	string
Body	uuid required	UUID of the task	string

Responses

HTTP Code	Description	Schema
200	Command Received	Response

GET /task/{uuid}/download/{asset}

Description

Retrieves an asset (the output of OpenDroneMap’s processing) associated with a task

Parameters

Type	Name	Description	Schema	Default
Path	asset required	Type of asset to download. Use "all.zip" for zip file containing all assets.	enum (all.zip)
Path	uuid required	UUID of the task	string
Query	token optional	Token required for authentication (when authentication is required).	string

Responses

HTTP Code	Description	Schema
200	Asset File	file
default	Error message	Error

Produces

• application/zip

Tags

• task

GET /task/{uuid}/info

Description

Gets information about this task, such as name, creation date, processing time, status, command line options and number of images being processed. See schema definition for a full list.

Parameters

Type	Name	Description	Schema	Default
Path	uuid required	UUID of the task	string
Query	token optional	Token required for authentication (when authentication is required).	string
Query	with_output optional	Optionally retrieve the console output for this task. The parameter specifies the line number that the console output should be truncated from. For example, passing a value of 100 will retrieve the console output starting from line 100. By default no console output is added to the response.	integer	"0"

Responses

HTTP Code	Description	Schema
200	Task Information	TaskInfo
default	Error	Error

TaskInfo

Name	Description	Schema
dateCreated required	Timestamp	integer
imagesCount required	Number of images	integer
name required	Name	string
options required	List of options used to process this task	< options > array
output optional	Console output for the task (only if requested via ?output=<linenum>)	< string > array
processingTime required	Milliseconds that have elapsed since the task started being processed.	integer
status required		status
uuid required	UUID	string

options

Name	Description	Schema
name required	Option name (example: "odm_meshing-octreeDepth")	string
value required	Value (example: 9)	string

status

Name	Description	Schema
code required	Status code (10 = QUEUED, 20 = RUNNING, 30 = FAILED, 40 = COMPLETED, 50 = CANCELED)	integer

Tags

• task

GET /task/{uuid}/output

Description

Retrieves the console output of the OpenDroneMap’s process. Useful for monitoring execution and to provide updates to the user.

Parameters

Type	Name	Description	Schema	Default
Path	uuid required	UUID of the task	string
Query	line optional	Optional line number that the console output should be truncated from. For example, passing a value of 100 will retrieve the console output starting from line 100. Defaults to 0 (retrieve all console output).	integer	"0"
Query	token optional	Token required for authentication (when authentication is required).	string

Responses

HTTP Code	Description	Schema
200	Console Output	string
default	Error	Error

Tags

• task

Definitions

Error

Name	Description	Schema
error required	Description of the error	string

Response

Name	Description	Schema
error optional	Error message if an error occured	string
success required	true if the command succeeded, false otherwise	boolean