Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

715 lines (492 sloc) 15.9 KB

node-opendronemap

Overview

REST API to access ODM

Version information

Version : 1.4.0

Contact information

Contact : Piero Toffanin

License information

License : GPL-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

maxImages
optional

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

odmVersion
optional

Current version of ODM

string

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

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

images
optional

Images to process, plus an optional GCP file. If included, the GCP file should have .txt extension

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

skipPostProcessing
optional

When set, skips generation of map tiles, derivate assets, 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 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

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

skipPostProcessing
optional

When set, skips generation of map tiles, derivate assets, 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 an optional GCP file. If included, the GCP file should have .txt extension

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, orthophoto.tif)

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

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

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

processingTime
required

Milliseconds that have elapsed since the task started being processed.

integer

status
required

Status code (10 = QUEUED, 20 = RUNNING, 30 = FAILED, 40 = COMPLETED, 50 = CANCELED)

integer

uuid
required

UUID

string

options

Name Description Schema

name
required

Option name (example: "odm_meshing-octreeDepth")

string

value
required

Value (example: 9)

string

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

You can’t perform that action at this time.