API Reference¶

This section covers interfaces of Delair.ai Python SDK.

Main interface¶

Entry point¶

Delair-Stack Python SDK has a unique entry point: The class DelairStackSDK.

class DelairStackSDK(*, config_path=None, user=None, password=None, client_id=None, secret=None, url=None, domain=None, proxy_url=None, **kwargs)¶

Entry point providing access to resource managers.

Resource managers are availables as instance attributes. The dir builtin can be used to list the availables managers.

The following examples show various ways to instantiate that class:

Using a username and a password:

>>> sdk = DelairStackSDK(user='admin1', password='password')

Using an API client identifier and secret:

>>> sdk = DelairStackSDK(client_id='72a5f676-6efc-48c5-ac07-4c534c3cdccc',
                         secret='52ccd77d-17e4-499b-995e-3a2731550723')

Using a configuration file:

>>> sdk = DelairStackSDK(config_path='/etc/python-delairstack/conf.json')

__init__(*, config_path=None, user=None, password=None, client_id=None, secret=None, url=None, domain=None, proxy_url=None, **kwargs)¶

Initializes Delair.ai Python SDK entry point.

Parameters

config_path (Optional[str]) – Optional path to a custom configuration file.
user (Optional[str]) – Optional username (email).
password (Optional[str]) – Optional password (mandatory if username is defined).
client_id (Optional[str]) – Optional client identifier.
secret (Optional[str]) – Optional client secret (mandatory if client_id is defined).
url (Optional[str]) – Optional platform URL (default https://www.delair.ai).
domain (Optional[str]) – Optional platform domain.
proxy_url (Optional[str]) – Optional proxy URL.
kwargs – Optional keyword arguments to merge with the configuration.

Configuration¶

class Config(defaults=None, custom=None, **kwargs)¶

Base class handling configuration.

It merges multiple sources of configuration and makes all configured properties available as instance attributes.

Three sources of configuration are handled:

The optional arguments given as kwargs.
A custom configuration file.
A default configuration.

__init__(defaults=None, custom=None, **kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

class ConnectionConfig(file_path=None, *, user=None, password=None, client_id=None, secret=None, url=None, domain=None, proxy_url=None, **kwargs)¶

Connection configuration.

__init__(file_path=None, *, user=None, password=None, client_id=None, secret=None, url=None, domain=None, proxy_url=None, **kwargs)¶

Initializes a connection configuration.

Parameters

file_path (Optional[str]) – Optional path to a custom configuration file.
user (Optional[str]) – Optional username (email).
password (Optional[str]) – Optional password (mandatory if username is defined).
client_id (Optional[str]) – Optional client identifier.
secret (Optional[str]) – Optional client secret (mandatory if client_id is defined).
url (Optional[str]) – Optional platform URL (default https://www.delair.ai).
domain (Optional[str]) – Optional domain.
proxy_url (Optional[str]) – Optional proxy URL.
kwargs –

Optional keyword arguments to merge with
the configuration.

kwargs : Optional arguments.

Three sources of configuration are merged:

The optional arguments kwargs.
The file at path file_path.
The default configuration.

The configuration file is expected to be written in JSON.

Resources management¶

class ResourcesManagerBase(*, provider, **kwargs)¶

Base class implementing resources management.

It provides default implementations of the following operations:

Resource creation
Search of resources
Retrieval of a resource by its identifier
Update of a resource
Deletion of a resource

create(**kwargs)¶

Creates a resource.

Parameters: **kwargs – Optional keyword arguments used as the description of the resource to create.
Returns: The created resource.
Return type: Resource

delete(*, resource)¶

Delete the given resource.

Parameters: resource (Resource) – The resource to delete.
Returns: It always returns True.
Return type: bool

get(*, id)¶

Get the resource with given identifier.

Parameters: id (str) – The resource identifire.
Returns: The resource with identifier equal to id.
Return type: Resource

search(*, query)¶

Search for resources matching the given query.

Parameters: query – Query that resources must match.
Returns: List of resources matching the search criteria.
Return type: [Resource]

The argument query is expected to be JSON serializable.

update(*, resource)¶

Update the resource.

Parameters: resource (Resource) – The resource to update.
Returns: The updated resource.
Return type: Resource

class Resource(id, *, desc, manager=None)¶

__init__(id, *, desc, manager=None)¶

Resource class.

Parameters

id (str) – Resource identifier.
desc (dict) – Resource description.
manager (Optional[object]) – Resource manager.

Returns

Resource created.

Return type

Resource

Errors¶

Package errors.

exception BoundingBoxError(msg='')¶

exception ConfigError(msg='')¶

exception DownloadError(msg='')¶

exception FileError(msg='')¶

exception ImmutableAttribute(name)¶

exception MissingCredentialsError(msg='')¶

exception ParameterError(msg='')¶

exception QueryError(msg='')¶

exception ResponseError(msg='')¶

exception SearchError(msg='')¶

exception TokenRenewalError(msg='')¶

exception UnsupportedOperationError¶

exception UnsupportedResourceError(resource_name)¶

exception UploadError(msg='')¶

Annotations¶

class AnnotationsImpl(annotations_api, sdk, **kwargs)¶

class Icons(value)¶: An enumeration.

add_attachments(annotation, *, attachments=None, file_paths=None, **kwargs)¶

Attach datasets to the annotation.

An attachment is a reference to a dataset handled by the Data Management API.

Items of the file_paths argument are interpreted as file paths on the host file system. For each item, a dataset is created and the file at the given path is uploaded. The dataset will be attached to the created annotation.

The created dataset has the following properties:

It’s type is equal to file or image depending on the local file MIME type.
It belongs to the same project as the annotation.
It’s named is equal to the basename of the local file.

For fine control of the dataset type, mission, published status, etc. or when the dataset has multiple components, one must create the dataset separately and use the attachment argument.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation to attach to.
attachments (Optional[List[NewType()(ResourceId, str)]]) – Identifiers of dataset to attach to the annotation.
file_paths (Optional[List[AnyStr]]) – List of file path to upload and attach to the annotation.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

create(*, project, mission=None, geometry=None, stroke=None, stroke_dasharray=None, icon=None, stroke_width=None, stroke_opacity=None, fill=None, fill_opacity=None, type='2d', target=None, name=None, description=None, followers=None, attachments=None, file_paths=None, normals=None, feature=None, flight=None, image=None, dataset=None, **kwargs)¶

Create an annotation.

Items of the file_paths argument are interpreted as file paths on the host file system. For each item, a dataset is created and the file at the given path is uploaded. The dataset will be attached to the created annotation.

Refer to add_attachments() for details on the properties of the created datasets.

Parameters

project (NewType()(ResourceId, str)) – Identifier of project to annotate.
mission (Optional[NewType()(ResourceId, str)]) – Identifier of mission to annotate.
type (AnyStr) – Annotation type (must be one of 2d, 3d and image).
geometry (Optional[dict]) – Geojson geometry of the annotation.
stroke (Optional[List[int]]) – Color used as annotation stroke list of integer [r,g,b] or [r,g,b,a].
stroke_dasharray (Optional[List[int]]) – List of integer for dasharray display (specify intervals of line and break).
icon (Union[Icons, str, None]) – Icon string or enum. Used for point annotations. Enum can be retrieved through sdk.annotations.Icons (default: sdk.annotations.Icons.ANNOTATE).
stroke_width (Optional[float]) – Width of stroke.
stroke_opacity (Optional[float]) – Opacity of stroke between 0 and 1.
fill (Optional[List[int]]) – Color used as fill for annotation list of integer [r,g,b] or [r,g,b,a]
fill_opacity (Optional[float]) – Opacity of fill between 0 and 1.
target (Optional[NewType()(ResourceId, str)]) – Identifier of the dataset to annotate. Using values such as 2d, 3d or photo is deprecated.
name (Optional[AnyStr]) – Annotation name.
description (Optional[AnyStr]) – Annotation description.
followers (Optional[List[NewType()(ResourceId, str)]]) – Identifiers of users following the annotation.
attachments (Optional[List[NewType()(ResourceId, str)]]) – Identifiers of datasets to attach to the annotation.
file_paths (Optional[List[AnyStr]]) – List of file paths to upload and attach to the annotation.
normals (Optional[List]) – Transformation vector used to transform the geometry on the front-end (for 3D datasets).
feature (Optional[dict]) – Deprecated Converted to geometry property if set.
image (Optional[NewType()(ResourceId, str)]) – Deprecated Used as target.id if set.
flight (Optional[NewType()(ResourceId, str)]) – Deprecated Not used.
dataset (Optional[NewType()(ResourceId, str)]) – Deprecated Used as target.id if set.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

The created annotation.

Return type

Resource

Examples

>>> sdk.annotations.create(
...    project='5d63cf9743d61400078efaf8',
...    geometry={
...        "type": "Point",
...        "coordinates": [1440.8495575221236, 1144.8259587020648]
...    },
...    name='My point annotation',
...    type='image',
...    target='5d63cf972fb3880011e57e34',
...    icon=sdk.annotations.Icons.CONVEYOR,
...    followers=['5d5fa52bc207040006390244'],
...    attachments=['5d63cf972fb3880011e57e32']
... )
<delairstack.core.resources.resource.Resource ... (annotations)>

create_annotations(annotations, **kwargs)¶

Create several annotations.

Parameters

annotations (List[dict]) – List of annotation descriptions, each description is a dictionary with keys among arguments of create().
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Return type

List[Resource]

Returns

Descriptions of the created annotations.

delete(annotation, **kwargs)¶

Delete an annotation or multiple annotations.

Parameters

annotation (NewType()(SomeResourceIds, Union[NewType()(ResourceId, str), List[NewType()(ResourceId, str)]])) – Identifier of the annotation to delete, or list of such identifiers.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

describe(annotation, **kwargs)¶

Describe a dataset or a list of datasets.

Parameters

annotation (NewType()(SomeResourceIds, Union[NewType()(ResourceId, str), List[NewType()(ResourceId, str)]])) – Identifier of the annotation to describe, or list of such identifiers.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Return type

NewType()(SomeResources, Union[Resource, List[Resource]])

Returns

The annotation description or a list of annotation description.

remove_attachments(annotation, *, attachments, **kwargs)¶

Remove attachment to the annotation.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation to remove attachments from.
attachments (NewType()(SomeResourceIds, Union[NewType()(ResourceId, str), List[NewType()(ResourceId, str)]])) – Identifier of attachments to remove.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

rename(annotation, *, name, **kwargs)¶

Rename the annotation.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation to rename.
name (str) – New name of the annotation.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

restore(annotation, **kwargs)¶

Restore an annotation or multiple annotations.

Parameters

annotation (NewType()(SomeResourceIds, Union[NewType()(ResourceId, str), List[NewType()(ResourceId, str)]])) – Identifier of the annotation to restore, or list of such identifiers.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

search(*, project=None, filter=None, limit=None, page=None, sort=None, return_total=False, **kwargs)¶

Search annotations.

Parameters

project (Optional[NewType()(ResourceId, str)]) – Optional identifier of a project to search annotatons for.
filter (Optional[dict]) – Search filter dictionary (refer to /search-annotations in the Annotation API specification for a detailed description).
limit (Optional[int]) – Maximum number of results.
page (Optional[int]) – Page number (starting at page 0).
sort (Optional[dict]) – Sort the results on the specified attributes (1 is sorting in ascending order, -1 is sorting in descending order).
return_total (bool) – Return the number of results found.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Return type

Union[ResourcesWithTotal, List[Resource]]

Returns

A list of annotation descriptions or a namedtuple with total number of results and list of annotation descriptions.

set_description(annotation, *, description, **kwargs)¶

Set the annotation description.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose description to set.
description (str) – Description of the annotation.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_fill_color(annotation, *, color, opacity=None, **kwargs)¶

Set the color used to fill the annotation.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose fill color to set.
color (List[float]) – Fill color to set interpreted as an RGB-triple.
opacity (Optional[float]) – Optional opacity of fill color, a float number between 0 and 1.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_fill_opacity(annotation, *, opacity, **kwargs)¶

Set the opacity of the annotation fill.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose fill opacity to set.
opacity (float) – Fill opacity to set.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_geometry(annotation, *, geometry, **kwargs)¶

Set the geometry of the annotation.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose geometry to set.
geometry (dict) – A dictionary following GeoJSON specification.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_icon(annotation, *, icon=None, **kwargs)¶

Set the annotation icon.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose icon to set.
icon (Union[Icons, str, None]) – Icon string or enum. Used for point annotations. Enum can be retrieved through sdk.annotations.Icons (default: sdk.annotations.Icons.ANNOTATE).
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_normals(annotation, *, normals, **kwargs)¶

Set the annotation normal vectors.

Setting the normals of an annotation makes sense for annotations of type 3d only. The argument normals is expected to be a list of 3-dimensional vectors, one for each vertice of the annotation geometry. Those vectors are interpreted as normals to the target of the annotation and are used to shift the annotation geometry when it is drawn so that it doesn’t overlap the target of the annotation and is drawn on the right side of the target facets.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose normal vector to set.
normals (List) – List of coordinates of normal vectors.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_stroke_color(annotation, *, color, opacity=None, **kwargs)¶

Set the stroke color of the annotation.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose stroke color to set.
color (Tuple[int, int, int]) – Stroke color to set interpreted as an RGB-triple.
opacity (Optional[float]) – Optional opacity of stroke color, a float number between 0 and 1.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_stroke_dasharray(annotation, *, dasharray, **kwargs)¶

Set the dasharray of the annotation stroke.

The dasharray defines the pattern of dashes and gaps used to paint the outline of the annotation.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose stroke opacity to set.
dasharray (List[float]) – Dasharray to set.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_stroke_opacity(annotation, *, opacity, **kwargs)¶

Set the opacity of the annotation stroke.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose stroke opacity to set.
opacity (float) – Stroke opacity to set.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

set_stroke_width(annotation, *, width, **kwargs)¶

Set the stroke width of the annotation.

Parameters

annotation (NewType()(ResourceId, str)) – Identifier of the annotation whose stroke width to set.
width (float) – Stroke width to set.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

update(*, resource)¶

Deprecated.

Return type: Resource

Comments¶

class CommentsImpl(ui_services_api, sdk, **kwargs)¶

create(text, *, project, type, target=None, flight=None, **kwargs)¶

Create a comment.

Parameters

text (str) – Comment content.
project (NewType()(ResourceId, str)) – Identifier of project to comment.
type (str) – Comment type (must be one of project, annotation, flight, photo, dataset, feature, gcp, task).
target (Optional[NewType()(ResourceId, str)]) – Optional identifier of the target.
flight (Optional[NewType()(ResourceId, str)]) – Optional identifier of the flight (mandatory when the comment type is photo).
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

The created comment.

Return type

Resource

Examples

>>> sdk.comments.create(
...    text='my comment',
...    project='5d63cf972fb3880011e57f22',
...    type='dataset',
...    target='5d63cf972fb3880011e57e34')
<delairstack.core.resources.comments.Comment ... (comments)>

mark_as_read(*, project, type=None, target=None, flight=None, **kwargs)¶

Mark all the comments of a target or project as read.

Parameters

project (NewType()(ResourceId, str)) – Identifier of project.
type (Optional[str]) – Optional comment type (must be one of project, annotation, flight, photo, dataset, feature, gcp, task).
target (Optional[NewType()(ResourceId, str)]) – Optional identifier of the target.
flight (Optional[NewType()(ResourceId, str)]) – Optional identifier of the flight (mandatory when the comment type is photo).
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Examples

>>> sdk.comments.mark_as_read(
...    project='5d63cf972fb3880011e57f22',
...    type='dataset',
...    target='5d63cf972fb3880011e57e34')

Return type: None

search(*, project, type=None, target=None, flight=None, **kwargs)¶

Search for comments.

When searching for comments on a photo. Both the flight id and target id must be supplied.

Parameters

project (NewType()(ResourceId, str)) – Identifier of the project.
type (Optional[str]) – Optional comment type (must be one of project, annotation, flight, photo, dataset, feature, gcp, task).
target (Optional[NewType()(ResourceId, str)]) – Optional identifier of the target.
flight (Optional[NewType()(ResourceId, str)]) – Optional identifier of the flight (mandatory when the comment type is photo).
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

The found comments.

Return type

Resources

Examples

>>> sdk.comments.search(project='5d63cf972fb3880011e57f22')
[<delairstack.core.resources.comments.Comment ... (comments)>]

Datasets¶

class DatasetsImpl(data_management_api, auth_api, **kwargs)¶

add_categories(dataset, *, categories, **kwargs)¶

Add categories to the dataset.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset to add categories to.
categories (List[str]) – Categories to add.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

create_datasets(datasets)¶

Create several datasets (bulk dataset creation).

Parameters: datasets (List[dict]) – List of dataset dictionnaries (refer to /create-datasets definition in the Data Manager API for a detailed description of datasets)
Return type: List[Resource]
Returns: A list of the created dataset descriptions.

Example

>>> sdk.datasets.create_datasets(
... datasets=[{'name': 'My file dataset',
...            'type': 'file',
...            'components': [{'name': 'kind_of_file'}]},
...           {'name': 'My image',
...            'type': 'image',
...            'components': [{'name': 'image'}]}])
[<delairstack.core.resources.resource.Resource... (dataset)>, ...]

create_file_dataset(*, name, categories=None, project=None, mission=None, hidden=None, published=None, horizontal_srs_wkt=None, vertical_srs_wkt=None, dataset_format=None, geometry=None, properties=None, file_count=1, components=None, **kwargs)¶

Create a dataset of type file.

Parameters

name (str) – Name of the dataset.
categories (Optional[Sequence[str]]) – Sequence of categories or None if there’s no category to set on the dataset.
project (Optional[NewType()(ResourceId, str)]) – Optional project identifier.
mission (Optional[NewType()(ResourceId, str)]) – Optional mission identifier.
hidden (Optional[bool]) – Whether not to display the dataset to end-users or not.
published (Optional[bool]) – Whether the dataset is ready for delivery or not.
horizontal_srs_wkt (Optional[str]) – Optional geographic coordinate system for horizontal coordinattes in WKT format.
vertical_srs_wkt (Optional[str]) – Optional geographic coordinate system for vertical coordinattes in WKT format.
dataset_format (Optional[str]) – Optional file format.
geometry (Optional[dict]) – Optional geometry of the dataset.
properties (Optional[dict]) – Optional custom properties of the dataset.
file_count (int) – Number of files. Default to 1. It is used to generate the component names automatically, except if components is defined.
components (Optional[List[str]]) – Optional sequence of component names. When defined, file_count is ignored.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

Resource for the created dataset.

Return type

Resource

create_image_dataset(*, name, categories=None, project=None, mission=None, flight=None, hidden=None, published=None, horizontal_srs_wkt=None, vertical_srs_wkt=None, dataset_format=None, geometry=None, properties=None, acquisition_date=None, width=None, height=None, sensor=None, lens=None, camera_parameters=None, reflectance_calibration_panel=None, **kwargs)¶

Create a dataset of type image.

Parameters

name (str) – Name of the dataset.
categories (Optional[Sequence[str]]) – Sequence of categories or None if there’s no category to set on the dataset.
project (Optional[NewType()(ResourceId, str)]) – Optional project identifier.
mission (Optional[NewType()(ResourceId, str)]) – Optional mission identifier.
flight (Optional[NewType()(ResourceId, str)]) – Optional flight identifier.
hidden (Optional[bool]) – Whether not to display the dataset to end-users or not.
published (Optional[bool]) – Whether the dataset is ready for delivery or not.
horizontal_srs_wkt (Optional[str]) – Optional geographic coordinate system for horizontal coordinattes in WKT format.
vertical_srs_wkt (Optional[str]) – Optional geographic coordinate system for vertical coordinattes in WKT format.
dataset_format (Optional[str]) – Optional file format.
geometry (Optional[dict]) – Optional geometry of the dataset.
properties (Optional[dict]) – Optional custom properties of the dataset.
acquisition_date (Optional[str]) – Optional acquisition date (format: YYYY-MM-DDTHH:MM:SS.sssZ).
width (Optional[int]) – Optional image width.
height (Optional[int]) – Optional image height.
sensor (Optional[dict]) – Optional sensor properties.
lens (Optional[dict]) – Optional lens properties.
camera_parameters (Optional[dict]) – Optional camera parameters description.
reflectance_calibration_panel (Optional[dict]) – Optional reflectance calibration panel description.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

Resource for the created dataset.

Return type

Resource

create_mesh_dataset(*, name, categories=None, project=None, mission=None, hidden=None, published=None, horizontal_srs_wkt=None, vertical_srs_wkt=None, dataset_format=None, geometry=None, properties=None, texture_count=1, material_count=1, offset=None, **kwargs)¶

Create a dataset of type mesh.

Parameters

name (str) – Name of the dataset.
categories (Optional[Sequence[str]]) – Sequence of categories or None if there’s no category to set on the dataset.
project (Optional[NewType()(ResourceId, str)]) – Optional project identifier.
mission (Optional[NewType()(ResourceId, str)]) – Optional mission identifier.
hidden (Optional[bool]) – Whether not to display the dataset to end-users or not.
published (Optional[bool]) – Whether the dataset is ready for delivery or not.
horizontal_srs_wkt (Optional[str]) – Optional geographic coordinate system for horizontal coordinattes in WKT format.
vertical_srs_wkt (Optional[str]) – Optional geographic coordinate system for vertical coordinattes in WKT format.
dataset_format (Optional[str]) – Optional file format.
geometry (Optional[dict]) – Optional geometry of the dataset.
properties (Optional[dict]) – Optional custom properties of the dataset.
texture_count – Number of texture files. Default to 1.
material_count – Number of materials files. Defaut to 1.
offset (Optional[NewType()(Offset, Tuple[float, float, float])]) – Optional translation from mesh coordinates to spatial coordinates.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

Resource for the created dataset.

Return type

Resource

create_pcl_dataset(*, name, categories=None, project=None, mission=None, hidden=None, published=None, horizontal_srs_wkt=None, vertical_srs_wkt=None, dataset_format=None, geometry=None, properties=None, **kwargs)¶

Create a dataset of type pcl.

Parameters

name (str) – Name of the dataset.
categories (Optional[Sequence[str]]) – Sequence of categories or None if there’s no category to set on the dataset.
project (Optional[NewType()(ResourceId, str)]) – Optional project identifier.
mission (Optional[NewType()(ResourceId, str)]) – Optional mission identifier.
hidden (Optional[bool]) – Whether not to display the dataset to end-users or not.
published (Optional[bool]) – Whether the dataset is ready for delivery or not.
horizontal_srs_wkt (Optional[str]) – Optional geographic coordinate system for horizontal coordinattes in WKT format.
vertical_srs_wkt (Optional[str]) – Optional geographic coordinate system for vertical coordinattes in WKT format.
dataset_format (Optional[str]) – Optional file format.
geometry (Optional[dict]) – Optional geometry of the dataset.
properties (Optional[dict]) – Optional custom properties of the dataset.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

Resource for the created dataset.

Return type

Resource

create_raster_dataset(*, name, categories=None, project=None, mission=None, hidden=None, published=None, horizontal_srs_wkt=None, vertical_srs_wkt=None, dataset_format=None, geometry=None, properties=None, bands=None, has_projection_file=False, has_worldfile=False, has_headerfile=False, **kwargs)¶

Create a dataset of type raster.

Parameters

name (str) – Name of the dataset.
categories (Optional[Sequence[str]]) – Sequence of categories or None if there’s no category to set on the dataset.
project (Optional[NewType()(ResourceId, str)]) – Optional project identifier.
mission (Optional[NewType()(ResourceId, str)]) – Optional mission identifier.
hidden (Optional[bool]) – Whether not to display the dataset to end-users or not.
published (Optional[bool]) – Whether the dataset is ready for delivery or not.
horizontal_srs_wkt (Optional[str]) – Optional geographic coordinate system for horizontal coordinattes in WKT format.
vertical_srs_wkt (Optional[str]) – Optional geographic coordinate system for vertical coordinattes in WKT format.
dataset_format (Optional[str]) – Optional file format.
geometry (Optional[dict]) – Optional geometry of the dataset.
properties (Optional[dict]) – Optional custom properties of the dataset.
bands (Optional[List[dict]]) – Option list of band properties.
has_projection_file (bool) – Whether there is a sidecar file to define the raster projection.
has_worldfile (bool) – Whether there is a sidecar file to georeference the raster.
has_headerfile (bool) – Whether there is a sidecar file for envi format raster.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

Resource for the created dataset.

Return type

Resource

create_vector_dataset(*, name, categories=None, project=None, mission=None, hidden=None, published=None, collection=None, origin=None, horizontal_srs_wkt=None, vertical_srs_wkt=None, dataset_format=None, geometry=None, properties=None, is_shape_file=False, is_archive=False, has_projection_file=False, **kwargs)¶

Create a dataset of type vector.

When is_archive is True, is_shape_file and has_projection_file must be False.

Parameters

name (str) – Name of the dataset.
categories (Optional[Sequence[str]]) – Sequence of categories or None if there’s no category to set on the dataset.
project (Optional[NewType()(ResourceId, str)]) – Optional project identifier.
mission (Optional[NewType()(ResourceId, str)]) – Optional mission identifier.
hidden (Optional[bool]) – Whether not to display the dataset to end-users or not.
published (Optional[bool]) – Whether the dataset is ready for delivery or not.
collection (Optional[NewType()(ResourceId, str)]) – Optional map-service collection to use as data source. Providing a collection isn’t compatible with setting is_shape_file, has_projection_file, is_archive to True, nor setting dataset_format.
origin (Optional[NewType()(ResourceId, str)]) – Optional origin vector dataset (source: data-manager) for a vector collection dataset (source: map-service).
horizontal_srs_wkt (Optional[str]) – Optional geographic coordinate system for horizontal coordinattes in WKT format.
vertical_srs_wkt (Optional[str]) – Optional geographic coordinate system for vertical coordinattes in WKT format.
dataset_format (Optional[str]) – Optional file format.
geometry (Optional[dict]) – Optional geometry of the dataset.
properties (Optional[dict]) – Optional custom properties of the dataset.
is_shape_file (bool) – Whether it is an ESRI Shapefile.
is_archive (bool) – Whether it is an archive.
has_projection_file (bool) – Whether there is a sidecar file to define the shapes projection.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

Resource for the created dataset.

Return type

Resource

delete(dataset, **kwargs)¶

Delete a dataset or multiple datasets.

Parameters

dataset (NewType()(SomeResourceIds, Union[NewType()(ResourceId, str), List[NewType()(ResourceId, str)]])) – Identifier of the dataset to delete, or list of such identifiers.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

delete_properties(dataset, *, properties, **kwargs)¶

Delete properties of the dataset.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset whose properties to delete.
properties (List[str]) – Names of properties to delete.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

describe(dataset, **kwargs)¶

Describe a dataset or a list of datasets.

Parameters

dataset (NewType()(SomeResourceIds, Union[NewType()(ResourceId, str), List[NewType()(ResourceId, str)]])) – Identifier of the dataset to describe, or list of such identifiers.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Return type

NewType()(SomeResources, Union[Resource, List[Resource]])

Returns

The dataset description or a list of dataset description.

download_component(dataset, *, component, target_path=None, target_name=None, overwrite=False, md5hash=None)¶

Download the file from a component.

If the path target_path doesn’t exists, it is created.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset to download from.
component (str) – Name of component to download from.
target_path (Optional[str]) – Path of directory where to save the downloaded file. Default to current directory.
target_name (Optional[str]) – Name of downloaded file. Default to the file name suggested by the server.
overwrite – Whether to overwrite an existing file. Default to False.
md5hash (Optional[str]) – Optional MD5 hash of the file to download read in binary mode and containing only hexadecimal digits. When not equal to None (the default), will be compared to the equivalent hash for the downloaded file.

Raises

DownloadError – When the MD5 hash of the downloaded file doesn’t match md5hash.

Return type

str

Returns

Path of the downloaded file.

download_image_as_jpeg(dataset, target_path=None, target_name=None, overwrite=False, md5hash=None)¶

Download an image as JPEG.

If the path target_path doesn’t exists, it is created.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset to download from.
target_path (Optional[str]) – Path of directory where to save the downloaded file. Default to current directory.
target_name (Optional[str]) – Name of downloaded file. Default to the file name suggested by the server.
overwrite – Whether to overwrite an existing file. Default to False.
md5hash (Optional[str]) – Optional MD5 hash of the file to download read in binary mode and containing only hexadecimal digits. When not equal to None (the default), will be compared to the equivalent hash for the downloaded file.

Raises

DownloadError – When the MD5 hash of the downloaded file doesn’t match md5hash.

Return type

str

Returns

Path of the downloaded file.

download_preview(dataset, target_path=None, target_name=None, overwrite=False)¶

Download a dataset preview.

If the path target_path doesn’t exists, it is created.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset to download from.
target_path (Optional[str]) – Path of directory where to save the downloaded file. Default to current directory.
target_name (Optional[str]) – Name of downloaded file. Default to the file name suggested by the server.
overwrite – Whether to overwrite an existing file. Default to False.

Return type

str

Returns

Path of the downloaded file.

remove_categories(dataset, *, categories, **kwargs)¶

Remove categories from the dataset.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset to remove categories from.
categories (List[str]) – Categories to remove.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

rename(dataset, *, name, **kwargs)¶

Rename the dataset.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset to rename.
name (str) – New name of the dataset.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

restore(dataset, **kwargs)¶

Restore a dataset or multiple datasets.

Parameters

dataset (NewType()(SomeResourceIds, Union[NewType()(ResourceId, str), List[NewType()(ResourceId, str)]])) – Identifier of the dataset to restore, or list of such identifiers.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

search(*, filter=None, limit=None, page=None, sort=None, return_total=False, **kwargs)¶

Search datasets.

Parameters

filter (Optional[dict]) – Search filter dictionary (refer to /search-datasets definition in the Data Manager API for a detailed description of filter).
limit (Optional[int]) – Maximum number of results to extract.
page (Optional[int]) – Page number (starting at page 0).
sort (Optional[dict]) – Sort the results on the specified attributes (1 is sorting in ascending order, -1 is sorting in descending order).
return_total (bool) – Return the number of results found.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Return type

Union[ResourcesWithTotal, List[Resource]]

Returns

A list of dataset descriptions OR a namedtuple with total number of results and list of dataset descriptions.

Examples

>>> sdk.datasets.search(filter={'name': {'$eq': 'My image'}})
[<delairstack.core.resources.resource.Resource ... (dataset)>, ...]

>>> sdk.datasets.search(filter={'name': {'$eq': 'My image'}},
...                     return_total=True)
ResourcesWithTotal(
    total=...,
    results=[<delairstack.core.resources.resource.Resource..., ...]
)

search_generator(*, filter=None, limit=50, **kwargs)¶

Search datasets and return results through a generator.

The generator allows the user not to care about the pagination of results, while being memory-effective. Found datasets are sorted chronologically in order to allow new datasets to be found during the search.

Parameters

filter (Optional[dict]) – Search filter dictionary (refer to /search-datasets definition in the Data Manager API for a detailed description of filter)
limit (int) – Optional maximum number of results by search request.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Return type

Generator[Resource, None, None]

Returns

A generator yielding each found dataset.

Examples

>>> datasets = sdk.datasets.search_generator(
...     filter={'name': {'$eq': 'My image'}})
>>> print(datasets)
<generator object DatasetsImpl.search_generator at ...>
>>> for dataset in datasets:
>>>     print(dataset)
<delairstack.core.resources.resource.Resource with id... (dataset)>

share_tiles(dataset, *, company=None, duration=None)¶

Return a URL template to share access to the tiles of a dataset.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset to create a URL for.
company (Optional[NewType()(ResourceId, str)]) – Optional identifier of a company to attach the created token too. When equal to None (the default), the user company is used.
duration (Optional[int]) – Optional duration in seconds of the created token. When equal to None (the default) the created token won’t expire.

Raises

UnsupportedResourceError – In case the dataset ingestion status isn’t equal to complete or its type isn’t raster or vector with mapservice source.

Return type

str

update_properties(dataset, *, properties, **kwargs)¶

Update the dataset properties.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset whose properties to update.
properties (dict) – Dictionary of properties to update.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

upload_file(dataset, *, component, file_path, md5hash=None, multipart=True, chunk_size=None)¶

Upload a file to a dataset component.

Parameters

dataset (NewType()(ResourceId, str)) – Identifier of the dataset to upload to.
component (str) – Name of component to upload to.
file_path (NewType()(AnyPath, Union[str, Path])) – Path to the file to upload.
md5hash (Optional[str]) – Optional MD5 hash of the file to upload read in binary mode and containing only hexadecimal digits. Will be computed when equal to None (the default).
multipart (bool) – Whether to upload the file using multipart upload. Default to True unless the file size is less than 5MB the file is upload in one request.
chunk_size (Optional[int]) – The size in byte of each part for a multipart upload. If file size is less than this number, multipart will not used. The value should be between 5MB and 50MB. 5MB is default.

Missions¶

class MissionsImpl(project_manager_api, ui_services_api, **kwargs)¶

complete_survey_upload(*, flight, status='complete')¶

Complete the survey upload.

It notifies the front-end that all the images have been uploaded. It is necessary after the create_survey. Otherwise, the upload progression bar will still be displayed.

Parameters

flight (NewType()(ResourceId, str)) – Flight identifier.
status (str) – Upload completion status (complete or 'failed).

Raises

QueryError – When the response is not consistent.

create(*, project, survey_date, number_of_images, name=None, **kwargs)¶

Creates a mission.

Based on the number of images to attach to the mission, this function calls create_survey() or create_mission().

Parameters

project (NewType()(ResourceId, str)) – Identifier of the project on which the mission is added.
survey_date (str) – Survey date of the mission (format: YYYY-MM-DDTHH:MM:SS.sssZ).
number_of_images (int) – Number of images that will be uploaded.
name (Optional[str]) – Optional mission name.
**kwargs – Optional arguments that will be merged into the mission description.

Returns

A tuple with the created flight and mission. Flight = None when the number of images is 0.

Return type

(Flight, Mission)

create_mission(*, project, survey_date, name=None, **kwargs)¶

Creates a mission without images.

This function is used when no image is attached to the mission. As a consequence, no flight will be created.

Parameters

project (NewType()(ResourceId, str)) – Identifier of the project on which the mission is added.
survey_date (str) – Survey date of the mission (format: YYYY-MM-DDTHH:MM:SS.sssZ).
name (Optional[str]) – Optional mission name.
**kwargs – Optional arguments that will be merged into the mission description.

Returns

The created mission.

Return type

Mission

create_survey(*, survey_date, project, number_of_images, name=None, coordinates=None, area=0, **kwargs)¶

Create a survey (mission + flight).

This function is used when images will be attached to the mission. As a consequence, a flight will be created as well.

Parameters

survey_date (str) – Survey date (format: YYYY-MM-DDTHH:MM:SS.sssZ).
project (NewType()(ResourceId, str)) – Project identifier on which the survey is added.
number_of_images (int) – Number of photos that will be uploaded.
name (Optional[str]) – Optional mission name.
coordinates (Optional[List]) – Coordinates bounding the mission to create.
area (float) – Optional survey area.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Raises

QueryError – The survey creation response is incorrect.

Returns

A tuple with the created flight and mission.

Return type

(Flight, Mission)

delete(mission)¶

Delete a mission.

Parameters: mission (NewType()(ResourceId, str)) – Identifier of the mission to delete.

search(*, missions=None, flights=None, project=None, deleted=False, name=None, **kwargs)¶

Search missions.

Parameters

missions (Optional[List[NewType()(ResourceId, str)]]) – Optional list of mission identifiers.
flights (Optional[List[NewType()(ResourceId, str)]]) – Optional list of flight identifiers.
project (Optional[NewType()(ResourceId, str)]) – Optional project identifier.
deleted (bool) – Optional parameter to search for deleted missions or not (False by default).
name (Optional[str]) – Deprecated Optional project, mission or flight name.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Raises

QueryError – When the response is not consistent.

Returns

List of missions matching the search criteria.

Return type

[Mission]

Examples

Get the missions related to a specific project:

>>> sdk.missions.search(project=my_project_resource.id)
[<delairstack.core.resources.projectmngt.missions.Mission...>, ...]

Mission resource¶

class Mission(**kwargs)¶

__init__(**kwargs)¶

Mission resource.

Parameters

id – Mission identifier.
name – Mission name.
project – Project identifier.
survey_date – Survey date (format: YYYY-MM-DDTHH:MM:SS.sssZ).
flights – List of flight identifiers.
geometry – Mission geometry.
created – Mission creation date (format: YYYY-MM-DDTHH:MM:SS.sssZ).
user – Mission creation user.
modification_date – Mission last modification date (format: YYYY-MM-DDTHH:MM:SS.sssZ).
modification_user – Mission last modification user.
real_bbox – Mission bounding box.

Returns

A mission resource.

Return type

Mission

Flight resource¶

class Flight(**kwargs)¶

__init__(**kwargs)¶

Flight resource.

Parameters

id – Flight identifier.
name – Flight name.
survey_date – Survey date (format: YYYY-MM-DDTHH:MM:SS.sssZ).
project – Project identifier.
mission – Mission identifier.
number_of_photos – Number of images in the flight.
created – Flight creation date.
user – Flight creation user.

Returns

A flight resource.

Return type

Flight

Projects¶

class ProjectsImpl(project_manager_api, ui_services_api, **kwargs)¶

create(**kwargs)¶

Create a project.

Parameters

name – Project name.
geometry – Optional project geometry.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Raises

QueryError – The project creation response is incorrect.

Returns

A resource encapsulating the created project.

Return type

Project

delete(project)¶

Delete the specified Project.

Parameters: project (NewType()(ResourceId, str)) – Identifier of the project to delete.
Return type: None

describe(project, deleted=False)¶

Describe the project for the specified id.

Parameters

project (NewType()(ResourceId, str)) – Project identifier.
deleted (bool) – Optional parameter to describe a deleted project or not (False by default).

Returns

Project resource matching the id (None if not found).

Return type

Project

Examples

>>> sdk.projects.describe('5ce7f379327e9d5f15e37bb4')
<delairstack.core.resources.projectmngt.projects.Project ...>

search(*, name, deleted=False, **kwargs)¶

Search for projects.

Parameters

name (str) – Name of the project (the comparison is case insensitive). * wildcard is supported
deleted (bool) – Optional parameter to search for deleted project or not (False by default).
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Raises

QueryError – When the response is not consistent.

Returns

List of project resources matching the search criteria.

Return type

[Project]

Examples

Get the projects with a specific name (name is not unique):

>>> sdk.projects.search(name='My_project')
[<delairstack.core.resources.projectmngt.projects.Project...>, ...]

Get all the projects available:

>>> sdk.projects.search(name='*')
[<delairstack.core.resources.projectmngt.projects.Project...>, ...]

update_status(project, status)¶

Update the project status.

Parameters

project (NewType()(ResourceId, str)) – Project identifier.
status (str) – Project status (pending, available, failed).

Raises

ResponseError – When the project has not been found.
RuntimeError – The passed status is not allowed.

Returns

Updated project resource.

Return type

Project

Project resource¶

class Project(**kwargs)¶

__init__(**kwargs)¶

Project resource.

Parameters

id – Project identifier.
name – Project name.
geometry – Project geometry.
industry – Project industry.
created – Project creation date (format: YYYY-MM-DDTHH:MM:SS.sssZ).
company – Project’s company identifier.
missions – Project’s mission identifiers.
user – Project creation user.
modification_date – Project last modification date (format: YYYY-MM-DDTHH:MM:SS.sssZ).
modification_user – Project last modification user.
real_bbox – Project bounding box.
place_name – Project place name.

Returns

A project resource.

Return type

Project

Tags¶

class TagsImpl(ui_services_api, sdk, **kwargs)¶

create(name, *, project, type, target=None, flight=None, **kwargs)¶

Create a tag.

Parameters

name (str) – Tag name.
project (NewType()(ResourceId, str)) – Identifier of project to tag.
type (str) – Tag type (must be one of project, annotation, flight, photo, dataset, feature, gcp, task).
target (Optional[NewType()(ResourceId, str)]) – Optional identifier of the target.
flight (Optional[NewType()(ResourceId, str)]) – Optional identifier of the flight (mandatory when the tag type is photo).
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

The created tag.

Return type

Tag

Examples

>>> sdk.tags.create(
...    name='my tag',
...    project='5d63cf972fb3880011e57f22',
...    type='dataset',
...    target='5d63cf972fb3880011e57e34')
<delairstack.core.resources.tags.Tag with id ... (tags)>

delete(tag)¶

Delete a tag.

Parameters

tag (NewType()(ResourceId, str)) – Identifier of the tag to delete.
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Examples

>>> sdk.tags.delete('5d63cf972fb3880011e57f22')

Return type: None

search(*, project, type=None, target=None, flight=None, **kwargs)¶

Search tags.

When searching for tags on a photo. Both the flight id and target id must be supplied.

Parameters

project (NewType()(ResourceId, str)) – Identifier of the project.
type (Optional[str]) – Optional tag type (must be one of project, annotation, flight, photo, dataset, feature, gcp, task).
target (Optional[NewType()(ResourceId, str)]) – Optional identifier of the target.
flight (Optional[NewType()(ResourceId, str)]) – Optional identifier of the flight (mandatory when the tag type is photo).
**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.

Returns

The found tags.

Return type

Resources

Examples

>>> sdk.tags.search(project='5d63cf972fb3880011e57f22')
[<delairstack.core.resources.tags.Tag with id ... (tags)>]