Welcome to PyODM’s documentation!

PyODM is a library for easily creating orthophotos, DEMs, 3D models and point clouds from aerial images via the NodeODM API. It’s an official WebODM project.

Installation:

pip install -U pyodm

Simple usage:

>>> import os
>>> from pyodm import Node
>>> n = Node('localhost', 3000)
>>> task = n.create_task(['examples/images/image_1.jpg', 'examples/images/image_2.jpg'], {'dsm': True})
>>> task.wait_for_completion()
>>> os.listdir(task.download_assets("results"))[0:2]
['odm_orthophoto', 'odm_dem']

To test these examples you need to start a NodeODM node via:

docker run -ti -p 3000:3000 webodm/nodeodm

Code Samples:

Getting Help / Reporting Issues:

PyODM is in active development. If you find an issue please report it. We welcome contributions, see the GitHub page for more information.

License: BSD 3-Clause, see LICENSE for more details.

API

class pyodm.api.Node(host, port, token='', timeout=30)

A client to interact with NodeODM API.

Parameters:

  • host (str) – Hostname or IP address of processing node

  • port (int) – Port of processing node

  • token (str) – token to use for authentication

  • timeout (int) – timeout value in seconds for network requests

create_task(files, options={}, name=None, progress_callback=None, skip_post_processing=False, webhook=None, outputs=[], parallel_uploads=10, max_retries=5, retry_timeout=5, task_uuid=None)

Start processing a new task. At a minimum you need to pass a list of image paths. All other parameters are optional.

>>> n = Node('localhost', 3000)
>>> t = n.create_task(['examples/images/image_1.jpg', 'examples/images/image_2.jpg'],                           {'orthophoto-resolution': 2, 'dsm': True})
>>> info = t.info()
>>> info.status
<TaskStatus.RUNNING: 20>
>>> info.last_error
''
>>> t.info().images_count
2
>>> t.output()[0:2]
['DJI_0131.JPG - DJI_0313.JPG has 1 candidate matches', 'DJI_0131.JPG - DJI_0177.JPG has 3 candidate matches']
Parameters:

  • files (list) – list of image paths + optional GCP file path.

  • options (dict) – options to use, for example {‘orthophoto-resolution’: 3, …}

  • name (str) – name for the task

  • progress_callback (function) – callback reporting upload progress percentage

  • skip_post_processing (bool) – When true, skips generation of map tiles, derivate assets, point cloud tiles.

  • webhook (str) – Optional URL to call when processing has ended (either successfully or unsuccessfully).

  • outputs (list) – Optional paths relative to the project directory that should be included in the all.zip result file, overriding the default behavior.

  • parallel_uploads (int) – Number of parallel uploads.

  • max_retries (int) – Number of attempts to make before giving up on a file upload.

  • retry_timeout (int) – Wait at least these many seconds before attempting to upload a file a second time, multiplied by the retry number.

  • task_uuid – an optional UUID string that will be used as UUID for this task instead of generating a random one.

Returns:

Task()

static from_url(url, timeout=30)

Create a Node instance from a URL.

>>> n = Node.from_url("http://localhost:3000?token=abc")
Parameters:

  • url (str) – URL in the format proto://hostname:port/?token=value

  • timeout (int) – timeout value in seconds for network requests

Returns:

Node()

get_task(uuid)

Helper method to initialize a task from an existing UUID

>>> n = Node("localhost", 3000)
>>> t = n.get_task('00000000-0000-0000-0000-000000000000')
>>> t.__class__
<class 'pyodm.api.Task'>
Parameters:

uuid – Unique identifier of the task

info()

Retrieve information about this node.

>>> n = Node('localhost', 3000)
>>> n.info().version
'1.5.3'
>>> n.info().engine
'odm'
Returns:

NodeInfo()

options()

Retrieve the options available for creating new tasks on this node.

>>> n = Node('localhost', 3000)
>>> n.options()[0].name
'pc-classify'
Returns:

[NodeOption()]

Return type:

list

url(url, query={})

Get a URL relative to this node.

Parameters:

  • url (str) – relative URL

  • query (dict) – query values to append to the URL

Returns:

Absolute URL

Return type:

str

version_greater_or_equal_than(version)

Checks whether this node version is greater than or equal than a certain version number.

>>> n = Node('localhost', 3000)
>>> n.version_greater_or_equal_than('1.3.1')
True
>>> n.version_greater_or_equal_than('10.5.1')
False
Parameters:

version (str) – version number to compare

Returns:

result of comparison.

Return type:

bool

class pyodm.api.Task(node, uuid)

A task is created to process images. To create a task, use create_task().

Parameters:

  • node (Node()) – node this task belongs to

  • uuid (str) – Unique identifier assigned to this task.

cancel()

Cancel this task.

Returns:

task was canceled or not

Return type:

bool

download_assets(destination, progress_callback=None, parallel_downloads=16, parallel_chunks_size=10)

Download this task’s assets to a directory.

Parameters:

  • destination (str) – directory where to download assets. If the directory does not exist, it will be created.

  • progress_callback (function) – an optional callback with one parameter, the download progress percentage

  • parallel_downloads (int) – maximum number of parallel downloads if the node supports http range.

  • parallel_chunks_size (int) – size in MB of chunks for parallel downloads

Returns:

path to saved assets

Return type:

str

download_zip(destination, progress_callback=None, parallel_downloads=16, parallel_chunks_size=10)

Download this task’s assets archive to a directory.

Parameters:

  • destination (str) – directory where to download assets archive. If the directory does not exist, it will be created.

  • progress_callback (function) – an optional callback with one parameter, the download progress percentage.

  • parallel_downloads (int) – maximum number of parallel downloads if the node supports http range.

  • parallel_chunks_size (int) – size in MB of chunks for parallel downloads

Returns:

path to archive file (.zip)

Return type:

str

info(with_output=None)

Retrieves information about this task.

Returns:

TaskInfo()

output(line=0)

Retrieve console task output.

Parameters:

line (int) – 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. Negative numbers are also allowed. For example -50 will retrieve the last 50 lines of console output. Defaults to 0 (retrieve all console output).

Returns:

console output (one list item per row).

Return type:

[str]

remove()

Remove this task.

Returns:

task was removed or not

Return type:

bool

restart(options=None)

Restart this task.

Parameters:

options (dict) – options to use, for example {‘orthophoto-resolution’: 3, …}

Returns:

task was restarted or not

Return type:

bool

wait_for_completion(status_callback=None, interval=3, max_retries=5, retry_timeout=5)

Wait for the task to complete. The call will block until the task status has become COMPLETED(). If the status is set to CANCELED() or FAILED() it raises a TaskFailedError exception.

Parameters:

  • status_callback (function) – optional callback that will be called with task info updates every interval seconds.

  • interval (int) – seconds between status checks.

  • max_retries (int) – number of repeated attempts that should be made to receive a status update before giving up.

  • retry_timeout (int) – wait N*retry_timeout between attempts, where N is the attempt number.

class pyodm.types.NodeInfo(json)

Information about a node

Parameters:

  • version (str) – Current API version

  • task_queue_count (int) – Number of tasks currently being processed or waiting to be processed

  • total_memory (int) – Amount of total RAM in the system in bytes

  • available_memory (int) – Amount of RAM available in bytes

  • cpu_cores (int) – Number of virtual CPU cores

  • max_images (int) – Maximum number of images allowed for new tasks or None if there’s no limit.

  • max_parallel_tasks (int) – Maximum number of tasks that can be processed simultaneously

  • odm_version (str) – Current version of ODM (deprecated, use engine_version instead)

  • engine (str) – Lowercase identifier of the engine (odm, micmac, …)

  • engine_version (str) – Current engine version

class pyodm.types.NodeOption(domain, help, name, value, type)

A node option available to be passed to a node.

Parameters:

  • domain (str) – Valid range of values

  • help (str) – Description of what this option does

  • name (str) – Option name

  • value (str) – Default value for this option

  • type (str) – One of: [‘int’, ‘float’, ‘string’, ‘bool’, ‘enum’]

class pyodm.types.TaskInfo(json)

Task information

Parameters:

  • uuid (str) – Unique identifier

  • name (str) – Human friendly name

  • date_created (datetime) – Creation date and time

  • processing_time (int) – Milliseconds that have elapsed since the start of processing, or -1 if no information is available.

  • status (pyodm.types.TaskStatus()) – status (running, queued, etc.)

  • last_error (str) – if the task fails, this will be set to a string representing the last error that occured, otherwise it’s an empty string.

  • options (dict) – options used for this task

  • images_count (int) – Number of images (+ GCP file)

  • progress (float) – Percentage progress (estimated) of the task

  • output ([str]) – Optional console output (one list item per row). This is populated only if the with_output parameter is passed to info().

class pyodm.types.TaskStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Task status

Parameters:

  • QUEUED – Task’s files have been uploaded and are waiting to be processed.

  • RUNNING – Task is currently being processed.

  • FAILED – Task has failed for some reason (not enough images, out of memory, etc.

  • COMPLETED – Task has completed. Assets are be ready to be downloaded.

  • CANCELED – Task was manually canceled by the user.

Indices and tables