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 ifusername
is defined).client_id (
Optional
[str
]) – Optional client identifier.secret (
Optional
[str
]) – Optional client secret (mandatory ifclient_id
is defined).url (
Optional
[str
]) – Optional platform URL (defaulthttps://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 ifusername
is defined).client_id (
Optional
[str
]) – Optional client identifier.secret (
Optional
[str
]) – Optional client secret (mandatory ifclient_id
is defined).url (
Optional
[str
]) – Optional platform URL (defaulthttps://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
-
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
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
orimage
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 of2d
,3d
andimage
).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 forpoint
annotations. Enum can be retrieved throughsdk.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 as2d
,3d
orphoto
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 togeometry
property if set.image (
Optional
[NewType()
(ResourceId
,str
)]) – Deprecated Used astarget.id
if set.flight (
Optional
[NewType()
(ResourceId
,str
)]) – Deprecated Not used.dataset (
Optional
[NewType()
(ResourceId
,str
)]) – Deprecated Used astarget.id
if set.**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.
- Returns
The created annotation.
- Return type
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 ofcreate()
.**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
- 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 forpoint
annotations. Enum can be retrieved throughsdk.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 argumentnormals
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.
-
class
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 ofproject
,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 isphoto
).**kwargs – Optional keyword arguments. Those arguments are passed as is to the API provider.
- Returns
The created comment.
- Return type
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 ofproject
,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 isphoto
).**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 andtarget
id must be supplied.- Parameters
project (
NewType()
(ResourceId
,str
)) – Identifier of the project.type (
Optional
[str
]) – Optional comment type (must be one ofproject
,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 isphoto
).**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 ofdatasets
)- 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 ifcomponents
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
-
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
-
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
-
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
-
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
-
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
andhas_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 settingis_shape_file
,has_projection_file
,is_archive
to True, nor settingdataset_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
-
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
- 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 toNone
(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 toNone
(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 offilter
).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 offilter
)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)>
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 toNone
(the default), the user company is used.duration (
Optional
[int
]) – Optional duration in seconds of the created token. When equal toNone
(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’traster
orvector
withmapservice
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 toTrue
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()
orcreate_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
-
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
-
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
-
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
-
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
-
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
-
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
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 supporteddeleted (
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 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
-
Tags¶
Create a tag.
- Parameters
name (
str
) – Tag name.project (
NewType()
(ResourceId
,str
)) – Identifier of project to tag.type (
str
) – Tag type (must be one ofproject
,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 isphoto
).**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 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 tags.
When searching for tags on a photo. Both the
flight
id andtarget
id must be supplied.- Parameters
project (
NewType()
(ResourceId
,str
)) – Identifier of the project.type (
Optional
[str
]) – Optional tag type (must be one ofproject
,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 isphoto
).**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)>]