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 OpenDroneMap 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 opendronemap/nodeodm

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.

For all development questions, please reach out on the Community Forum.

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)

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

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