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_detector(detector_id: str, name: str | None = None, detection_type: str | None = None, output_type: str | None = None, training_steps: int | None = None, backbone: str | None = None, tile_size: int | None = None, background_sample_ratio: float | None = None)[source]
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
- edit_raster(raster_id: str, name: str | None = None, folder_id: str | None = None, captured_at: str | None = None, identity_key: str | None = None, multispectral_band_specification: dict | None = None, cloud_coverage: int | None = None, user_tag: str | None = None)[source]
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]
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_rasters(folder_id: str | None = None, search_string: str | None = None, user_tag: str | None = None, max_cloud_coverage: int | None = None, captured_before: str | None = None, captured_after: str | None = None, has_vector_layers: bool | None = None, page_number: int | None = None)[source]
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)]] ]