Getting started

Installation

Install using pip

pip install picterra

Set your Picterra API key through an environment variable

export PICTERRA_API_KEY=<your api key>

Listing entities

When listing entities (eg rasters, detectors) from your account, the Picterra Server uses a paginated approach; this means that every list_-prefixed function returns a special ResultsPage class instance which has the following properties, similarly to a Python list: * is iterable over the elements in the page, eg with a for * can be applied the builtin len to get the number of elements in the page * returns the n-th element of the page simply accessing with [n] (0-indexed) * has a next() method which returns the following ResultsPage, if any, otherwise None

#!/usr/bin/env python3

from picterra import APIClient

# Set the PICTERRA_API_KEY environment variable to define your API key
client = APIClient()

# Create a new detector (its type is 'count' by default)
detector_id = client.create_detector("My first detector")

# Edit the above detector
client.edit_detector(detector_id, "Renamed detector", "segmentation", "bbox", 1000)

# List existing detectors
detectors_page_1 = client.list_detectors()
print("Page has " + str(len(detectors_page_1)) + " elements")
d = detectors_page_1[0]
print(
    "detector id=%s, name=%s, detection_type=%s, output_type=%s, training_steps=%d"
    % (
        d["id"],
        d["name"],
        d["configuration"]["detection_type"],
        d["configuration"]["output_type"],
        d["configuration"]["training_steps"],
    )
)

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from pprint import pprint

from picterra import APIClient

# Set the PICTERRA_API_KEY environment variable to define your API key
client = APIClient()
# The Id of a folder/project you own
folder_id = "7ec40c11-f181-436a-9d33-d7b3f63e0e0f"
# Upload
local_raster_id = client.upload_raster("data/raster1.tif", name="A nice raster")
print("Uploaded local raster=", local_raster_id)
# Get the first batch of most recent images
first_page = client.list_rasters()
for raster in first_page:
    pprint("raster %s" % "\n".join(["%s=%s" % item for item in raster.items()]))
# Get the second batch
second_page = first_page.next()
# Get the first page applying a filter
for raster in client.list_rasters(folder_id):
    pprint("raster %s" % "\n".join(["%s=%s" % item for item in raster.items()]))
# Upload and removal
local_raster_id = client.upload_raster("data/raster1.tif", name="A short-lived raster")
print("Uploaded a second local raster=", local_raster_id)
client.delete_raster(local_raster_id)
print("Deleted raster=", local_raster_id)

Upload & Detect

from picterra import APIClient

# Replace this with the id of one of your detectors
detector_id = "d552605b-6972-4a68-8d51-91e6cb531c24"
# Replace this with the id of a folder in which the
# raster should be uploaded.
folder_id = "63207fe9-32b8-410f-a72d-00803cca7bf3"

# Set the PICTERRA_API_KEY environment variable to define your API key
client = APIClient()
print("Uploading raster...")
raster_id = client.upload_raster(
    "data/raster1.tif",
    name="a nice raster",
    folder_id=folder_id,
    captured_at="2020-01-01T12:34:45.789Z",
)
print("Upload finished, starting detector...")
result_id = client.run_detector(detector_id, raster_id)
client.download_result_to_feature_collection(result_id, "result.geojson")
print("Detection finished, results are in result.geojson")

Training

Note

Please note the below endpoints are still in beta and thus may be subject to change

#!/usr/bin/env python3

import json

from picterra import APIClient

# Set the PICTERRA_API_KEY environment variable to define your API key
client = APIClient()

# Create a new detector (its type is 'count' by default)
detector_id = client.create_detector("My first detector")

# Upload a training raster for the detector above
raster_id = client.upload_raster("data/raster1.tif", name="a nice raster")
client.add_raster_to_detector(raster_id, detector_id)

# Add annotations
with open("data/outline.geojson") as f:
    outlines = json.load(f)
client.set_annotations(detector_id, raster_id, "outline", outlines)
with open("data/training_area.geojson") as f:
    training_areas = json.load(f)
client.set_annotations(detector_id, raster_id, "training_area", training_areas)
with open("data/validation_area.geojson") as f:
    validation_areas = json.load(f)
client.set_annotations(detector_id, raster_id, "validation_area", validation_areas)

# Train the detector
client.train_detector(detector_id)

# At this point your detector is ready to predict: see upload_and_detect.py in order
# to launch a prediction on a raster; you can also use one of the raster already added above.

Detections in image coordinates

If you want to use Picterra with images that are not georeferenced and want to get the detector outputs in (x, y) coordinates, have a look at our nongeo_imagery notebook .

More examples

Check the examples directory of our github repo.