API

APIClient

class picterra.client.APIClient(timeout: int = 30, max_retries: int = 3, backoff_factor: int = 10)[source]

Main client class for the Picterra API

add_raster_to_detector(raster_id: str, detector_id: str)[source]

Associate a raster to a detector

This a beta function, subject to change.

Parameters:

detector_id – The id of the detector
raster_id – The id of the raster

Raises:

APIError – There was an error uploading the file to cloud storage

create_detector(name: str | None = None, detection_type: str = 'count', output_type: str = 'polygon', training_steps: int = 500, backbone: str = 'resnet34', tile_size: int = 256, background_sample_ratio: float = 0.25) → str[source]

Creates a new detector

This a beta function, subject to change.

Please note that depending on your plan some setting cannot be different from the default ones

Parameters:

name – Name of the detector
detection_type – Type of the detector (one of ‘count’, ‘segmentation’)
output_type – Output type of the detector (one of ‘polygon’, ‘bbox’)
training_steps – Training steps the detector (integer between 500 & 40000)
backbone – detector backbone (one of ‘resnet18’, ‘resnet34’, ‘resnet50’)
tile_size – tile size (see HTTP API docs for the allowed values)
background_sample_ratio – bg sample ratio (between 0 and 1)

Returns:

The id of the detector

Raises:

APIError – There was an error while creating the detector

create_marker(raster_id: str, detector_id: str | None, lng: float, lat: float, text: str) → dict[str, Any][source]

This is an experimental (beta) feature

Creates a marker

Parameters:

raster_id – The id of the raster (belonging to detector) to create the marker on
detector_id – The id of the detector to create the marker on. If this is None, the marker is created associated with the raster only

Raises:

APIError – There was an error while creating the marker

delete_detector(detector_id: str)[source]

Deletes a given detector by its identifier

Parameters:: detector_id – The id of the detector to delete
Raises:: APIError – There was an error while trying to delete the detector

delete_raster(raster_id: str)[source]

Deletes a given raster by its identifier

Parameters:: raster_id – The id of the raster to delete
Raises:: APIError – There was an error while trying to delete the raster

delete_vector_layer(vector_layer_id: str)[source]

Removes a vector layer

This a beta function, subject to change.

Parameters:: vector_layer_id – The id of the vector layer to remove

download_operation_results_to_file(operation_id: str, filename: str)[source]

Downloads the results URL to a local GeoJSON file

Parameters:

operation_id – The id of the operation to download
filename – The local filename where to save the results

download_raster_to_file(raster_id: str, filename: str)[source]

Downloads a raster to a local file

Parameters:

raster_id – The id of the raster to download
filename – The local filename where to save the raster image

Raises:

APIError – There was an error while trying to download the raster

download_result_to_feature_collection(operation_id: str, filename: str)[source]

Downloads the results from a detection operation to a local GeoJSON file.

Results are stored as a FeatureCollection of Multipolygon. Each feature has a ‘class_name’ property indicating the corresponding class name

Parameters:

operation_id – The id of the operation to download. This should be a detect operation
filename – The local filename where to save the results

download_result_to_file(operation_id: str, filename: str)[source]

Downloads a set of results to a local GeoJSON file

Deprecated since version 1.0.0: Use download_result_to_feature_collection instead

Parameters:

operation_id – The id of the operation to download
filename – The local filename where to save the results

download_vector_layer_to_file(vector_layer_id: str, filename: str)[source]

Downloads a vector layer

This a beta function, subject to change.

Parameters:

vector_layer_id – The id of the vector layer to download
filename – existing file to save the vector layer in

Edit a detector

This a beta function, subject to change.

Please note that depending on your plan some settings may not be editable.

Parameters:

detector_id – identifier of the detector
name – Name of the detector
detection_type – The type of the detector (one of ‘count’, ‘segmentation’)
output_type – The output type of the detector (one of ‘polygon’, ‘bbox’)
training_steps – The training steps the detector (int in [500, 40000])
backbone – detector backbone (one of ‘resnet18’, ‘resnet34’, ‘resnet50’)
tile_size – tile size (see HTTP API docs for the allowed values)
background_sample_ratio – bg sample ratio (between 0 and 1)

Raises:

APIError – There was an error while editing the detector

Edits an already existing raster.

Parameters:

name – New human-readable name for this raster
folder_id – Id of the new folder for this raster (move is in another project)
captured_at – new ISO-8601 date and time at which this raster was captured, YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]; e.g. “2020-01-01T12:34:56.789Z”
identity_key – New personal identifier for this raster.
multispectral_band_specification – The new band specification, see https://docs.picterra.ch/advanced-topics/multispectral
cloud_coverage – Raster cloud coverage new percentage
user_tag (beta) – Raster tag

Returns:

The id of the edited raster

Return type:

raster_id

edit_vector_layer(vector_layer_id: str, name: str | None = None, color: str | None = None)[source]

Edits a vector layer

This a beta function, subject to change.

Parameters:

vector_layer_id – The id of the vector layer to remove
name – new name
color – new color

get_operation_results(operation_id: str) → dict[str, Any][source]

Return the ‘results’ dict of an operation

This a beta function, subject to change.

Parameters:: operation_id – The id of the operation

get_operation_results_url(operation_id: str) → str[source]

Get the URL of a set of operation results

This a beta function, subject to change.

Parameters:: operation_id – The id of the result

get_raster(raster_id: str) → dict[str, Any][source]

Get raster information

Parameters:: raster_id – id of the raster
Raises:: APIError – There was an error while getting the raster information
Returns:: Dictionary of the information
Return type:: dict

import_raster_from_remote_source(raster_name: str, folder_id: str, source_id: str, aoi_filename: str, method: Literal['streaming'] = 'streaming') → str[source]

This is an experimental feature

Import a raster from a remote imagery source given a GeoJSON file for the AOI

Parameters:

raster_name – Name of the new raster
folder_id – The id of the folder / project the raster will live in
source_id – The id of the remote imagery source to import from
filename – The filename of a GeoJSON file. This should contain a FeatureCollection of Polygon/MultiPolygon representing the AOI of the new raster

Raises:

APIError – There was an error during import

list_detectors(search_string: str | None = None, user_tag: str | None = None, is_shared: bool | None = None, page_number: int | None = None)[source]

List all the detectors the user can access, see ResultsPage: for the pagination access pattern.

Parameters:

search_string – The term used to filter detectors by name
user_tag – [beta] User tag to filter detectors by
is_shared – [beta] Share status to filter detectors by
page_number – Optional page (from 1) of the list we want to retrieve

Returns:

A list of detectors dictionaries

Example

{
    'id': '42',
    'name': 'cow detector',
    'configuration': {
        'detection_type': 'count',
        'output_type': 'bbox',
        'training_steps': 787
    }
},
{
    'id': '43',
    'name': 'test5',
    'configuration': {
        'detection_type': 'segmentation',
        'output_type': 'polygon',
        'training_steps': 500
    }
}

list_folder_detectors(folder_id: str, page_number: int | None = None)[source]

List of detectors assigned to a given folder, see ResultsPage for the pagination access pattern.

This a beta function, subject to change.

Parameters:

folder_id – The id of the folder to obtain the detectors for
page_number – Optional page (from 1) of the list we want to retrieve

Returns:

A ResultsPage object that contains a slice of the list of detector dictionaries, plus methods to retrieve the other pages

Example

{
    "id": "id1",
    "name": "detector1",
    "is_runnable": True,
    "user_tag": "tag1",
},
{
    "id": "id2",
    "name": "detector2",
    "is_runnable": False,
    "user_tag": "tag2",
}

list_raster_markers(raster_id: str, page_number: int | None = None)[source]

This a beta function, subject to change.

List all the markers on a raster, see ResultsPage for the pagination access pattern.

Parameters:

raster_id – The id of the raster
page_number – Optional page (from 1) of the list we want to retrieve

list_raster_vector_layers(raster_id: str, search: str | None = None, detector_id: str | None = None, page_number: int | None = None)[source]

This a beta function, subject to change.

List all the vector layers on a raster, see ResultsPage: for the pagination access pattern.

Parameters:

raster_id – The id of the raster
search – Optional string to search layers by name
page_number – Optional page (from 1) of the list we want to retrieve

List of rasters metadata, see ResultsPage for the pagination access pattern.

Parameters:

folder_id – The id of the folder to search rasters in
search_string – The search term used to filter rasters by name
user_tag – [beta] The user tag to filter rasters by
max_cloud_coverage – [beta] The max_cloud_coverage of the rasters (between 0 and 100)
captured_before – ISO 8601 -formatted date / time of capture we want to list the rasters since
captured_after – ISO 8601 -formatted date / time of capture we want to list the rasters from
has_vector_layers – [beta] Whether or not the rasters have at least one vector layer
page_number – Optional page (from 1) of the list we want to retrieve

Returns:

A list of rasters dictionaries

Example

{
    'id': '42',
    'status': 'ready',
    'name': 'raster1',
    'folder_id': 'abc'
},
{
    'id': '43',
    'status': 'ready',
    'name': 'raster2',
    'folder_id': 'def'
}

remove_raster_detection_areas(raster_id: str)[source]

This is an experimental feature

Remove the detection areas of a raster

Parameters:: raster_id – The id of the raster whose detection areas will be removed
Raises:: APIError – There was an error during the operation

run_advanced_tool(tool_id: str, inputs: dict[str, Any], outputs: dict[str, Any])[source]

This is an experimental feature

Runs a tool and waits for its execution, returning the finished operation metadata

Parameters:

tool_id – The id of the tool to run
inputs – tool inputs
outputs – tool outputs

Raises:

APIError – There was an error while launching and executing the tool

run_dataset_recommendation(detector_id: str)[source]

This is an experimental feature

Runs dataset recommendation on a detector. Note that you currently have to use the UI to be able to view the recommendation markers/report.

Parameters:: detector_id – The id of the detector

run_detector(detector_id: str, raster_id: str) → str[source]

Runs a detector on a raster: predictions are subject to a minimum charge of 10 MP.

Parameters:

detector_id – The id of the detector
raster_id – The id of the raster

Returns:

The id of the operation. You typically want to pass this: to download_result_to_feature_collection

Return type:

operation_id

set_annotations(detector_id: str, raster_id: str, annotation_type: Literal['outline', 'training_area', 'testing_area', 'validation_area'], annotations: dict[str, Any])[source]

Replaces the annotations of type ‘annotation_type’ with ‘annotations’, for the given raster-detector pair.

Parameters:

detector_id – The id of the detector
raster_id – The id of the raster
annotation_type – One of (outline, training_area, testing_area, validation_area)
annotations – GeoJSON representation of the features to upload

set_raster_detection_areas_from_file(raster_id: str, filename: str)[source]

This is an experimental feature

Set detection areas from a GeoJSON file

Parameters:

raster_id – The id of the raster to which to assign the detection areas
filename – The filename of a GeoJSON file. This should contain a FeatureCollection of Polygon/MultiPolygon

Raises:

APIError – There was an error uploading the file to cloud storage

train_detector(detector_id: str)[source]

Start the training of a detector

Parameters:: detector_id – The id of the detector

upload_raster(filename: str, name: str, folder_id: str | None = None, captured_at: str | None = None, identity_key: str | None = None, multispectral: bool = False, cloud_coverage: int | None = None, user_tag: str | None = None) → str[source]

Upload a raster to picterra.

Parameters:

filename – Local filename of raster to upload
name – A human-readable name for this raster
folder_id – Id of the folder this raster belongs to; if not provided, the raster will be put in the “Picterra API Project” folder
captured_at – ISO-8601 date and time at which this raster was captured, YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]; e.g. “2020-01-01T12:34:56.789Z”
identity_key – Personal identifier for this raster.
multispectral – If True, the raster is in multispectral mode and can have an associated band specification
cloud_coverage – Raster cloud coverage %.
user_tag (beta) – Raster tag

Returns:

The id of the uploaded raster

Return type:

raster_id

upload_vector_layer(raster_id: str, filename: str, name: str | None = None, color: str | None = None) → str[source]

Uploads a vector layer from a GeoJSON file

This a beta function, subject to change.

Parameters:

raster_id – The id of the raster we want to attach the vector layer to
filename – Path to the local GeoJSOn file we want to upload
name – Optional name to give to the vector layer
color – Optional color of the vector layer, has an HTML hex color code (eg “#aabbcc”)

Returns;: the vector layer unique identifier

Pagination

class picterra.client.ResultsPage(url: str, fetch: Callable[[str], Response])[source]

Interface for a paginated response from the API

Typically the endpoint returning list of objects return them splitted in pages (page 1, page 2, etc..) of a fixed dimension (eg 20). Thus each list_XX function returns a ResultsPage (by default the first one); once you have a ResultsPage for a given list of objects, you can: * check its length with len() (eg len(page)) * access a single element with the index operator [] (eg page[5]) * turn it into a list of dictionaries with list() (eg list(page)) * get the next page with .next() (eg page.next()); this could return None if the list is finished You can also get a specific page passing the page number to the list_XX function

nongeo

picterra.nongeo.nongeo_result_to_pixel(result_filename)[source]

This is a helper function to convert result obtained on non-georeferenced images in pixel. Note that this will NOT work if the image was georeferenced. So only use this function if you are uploading non-georeferenced image formats like PNG or JPEG

This is currently in beta so let us know if you find any issues

Parameters:

result_filename (str) – The file path to the GeoJSON file obtained by APIClient.download_result_to_file

Returns:

A list of polygons. Each polygon is a list of rings and each ring is a list of (x, y) tuples. For example:

[
    # This is a square with a square hole
    [[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)],
     [(0.4, 0.4), (0.5, 0.4), (0.5, 0.5), (0.4, 0.5), (0.4, 0.4)],
    # A triangle
    [[(0, 0), (1, 0), (1, 1), (0, 0)]]
]

Exceptions

class picterra.client.APIError[source]: Generic API error exception