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/")