dymaxionlabs

This is the Python package for accessing the Dymaxion Labs Platform.

Features

The Dymaxion Labs Platform allows you:

  • Download and upload satellite and drone images.
  • Train machine learning models for object detection, segmentation, change detection, and more.
  • Work your data using a REST API and Python.

This is a publicly installable package. However, if you want access to our full Platform, you will need to create a Dymaxion Labs account.

Install

The package is currently in beta, so we recommend to install it via pip from the GitHub repository:

pip install git+https://github.com/dymaxionlabs/python-sdk.git

To install the latest stable version:

pip install dymaxionlabs

Authentication

Sign up at https://app.dymaxionlabs.com/signup if you do not have a user yet, otherwise log in.

Enter the API Key section, create a new API key and copy the generated key.

You need to set the API key using an environment variable, like this:

export DYM_API_KEY=...

You can also do this from Python:

import os

os.environ["DYM_API_KEY"] = "insert-api-key"

From now on, you have full access to the Dymaxion Labs API from Python.

Tutorial

Suppose you want to detect pools in a residential area. First, you need to create an Estimator. In this case, you want an “object_detection” type of model, and there is only one class of object.

from dymaxionlabs.models import Estimator

pools_detector = Estimator.create(name="Pools detector",
                                  type="object_detection",
                                  classes=["pool"])

Now, you should upload the images you want to use for training, add them to your estimator, and create the tiles from the image.

from dymaxionlabs.files import File

img = File.upload("pools-2020-02-01.tif", "pools/images/")
pools_detector.add_image(img)

tiling_task = img.tiling(output_path="pools/tiles/")
tiling_task.is_running()
#=> True

The tiling process generates tiles of 500x500 by default, but you can adjust the tile size with the tile_size parameter.

# Tile image in 250x250
tiling_task = img.tiling(output_path="pools/tiles-250/", tile_size=250)

Next step is to upload your labels file (GeoJSON file) and add them to your estimator. The labels file must be a GeoJSON of polygons for a specific class. If you have more than one class, you have to separate your labels in different files for each class.

labels = File.upload("labels.geojson", 'pools/labels/')
pools_detector.add_labels_for(labels, img, "pool")

Now you are ready to train the model. Training might take a few hours to finish, so the train() method returns a Task instance, that represents the current training task.

train_task = pools_detector.train()
train_task.is_running()
#=> True

You can adjust a few parameters when training by updating the configuration dictionary:

# Adjust configuration
pools_detector.configuration.update(epochs=25, steps=500)
# Re-train
train_task = pools_detector.train()

Currently there are two training parameters:

  • epochs: Number of training epochs (default=15)
  • steps: Number of steps per epoch (default=1000)

When the task finishes, your model will be ready to be used for prediction.

Unless you want to predict over the same image you used for training, you should upload another image and again, create the tiles for that image.

predict_img = File.upload("pools.tif", 'pools/predict-images/')
predict_tiles_folder = 'pools/predict-tiles/'
tiling_task = predict_img.tiling(output_path=predict_tiles_folder)
tiling_task.is_running()
#=> True

You are now ready to start a prediction task. This process might take a few minutes.

prediction_task = pools_detector.predict_files([predict_tiles_folder])
prediction_task.is_running()
#=> True

You can download the results when the prediction task has completed. The prediction task will generate the results as _output artifacts_, which you can download or export to your storage:

prediction_task.list_artifacts()
#=> ["pools.tif/results.csv", "pools.tif/results.geojson"]
prediction_task.download_artifacts("results/")

Indices and tables