OpenSpaceNet User Guide

OpenSpaceNet User Guide

OpenSpaceNet is our command line tool built on our DeepCore SDK that allows a user to download, perform object detection, and manipulate geospatial vector files. We felt it would be a good idea to give examples and descriptions of OpenSpaceNet’s most popular features. We hope that with this guide you can also create detections that look like this:

What is possible with OpenSpaceNet detection


The most basic command line run would be running your model on a local image. OpenSpacenet would only require 4 arguments in this case. Using detect lets OpenSpaceNet know that you would like to perform detection on your image. The model argument requries that you put the path to your model that you’ve trained on your object of interest, in this case my_model.gbdxm. Now we need to specify our output file which will store the polygon detects produced by our model. Finally, we’ll need to to provide the image path that we’d like to run detection on.

Local image:

OpenSpaceNet detect --model my_model.gbdxm --output output.shp --image my_image.tif

All the models we use output a confidence score for each detection. Setting a confidence threshold can be useful for filtering out detects with low scores. If you don’t set this parameter, the default value is set at 95


OpenSpaceNet detect --model my_model.gbdxm --output output.shp --image my_image.tif --confidence 30

In order to accurately detect all objects in an image we include some overlap in each iteration of the scan. However, this causes multiple detection boxes to be created for only one object. To clean these detects up, we have non-maximum suppression (NMS). When two or more detects overlap more then the nms percentage value, only the one with the highest confidence is retained. The default value is set at 30.


OpenSpaceNet detect --model my_model.gbdxm --output output.shp --image my_image.tif --confidence 30 --nms 60

OpenSpaceNet is also capable of pulling imagery from a WMS. We’ve built in connections to the popular DigitalGlobe web services, but you can also connect to any WMS service using the command line below.


OpenSpaceNet detect --bbox -84.44579 33.63404 -84.40601 33.64583 --model my_model.gbdxm --output output.shp --token my_wms_token --credentials user:password --service wms --url my_wms_url

If you’re not a fan of shapefile, OpenSpaceNet can output in csv, geojson, kml and many other services.

Geojson Ouput:

OpenSpaceNet detect --model my_model.gbdxm --output output.geojson --image my_image.tif

We are heavy users of PostGIS, which is a database that is highly optimized to store a large amount of geospatial vectors. Here is an example of how to store your results into PostGIS. Note: the append flag is very important. Without it, your table will be overwritten.

PostGIS Output:

OpenSpaceNet detect --model my_model.gbdxm --format postgis --output "PG:dbname=name host=host_ip user=my_user password=my_pass" --image my_image.tif --output-layer my_table_name --append

Metadata about each detect is extremely important, so in OpenSpaceNet we’ve added a feature where you can add any arbitrary attribute to each and every detect. Some metadata you might want to add are the image you ran detection on, the model you used or which user ran the process.

Extra Fields:

OpenSpaceNet detect --model my_model.gbdxm --output output.shp --image my_image.tif --extra-fields image_name my_image.tif model_id my_model.gbdxm ingested_by kevin_mcgee

Geospatial imagery can be huge (sometimes over 100GB), so we have a feature in OpenSpacenet that allows you to specify areas of the image that you don’t want processed, saving time and money. For instance, if you are trying to detect cars, you should add a water mask region to your exclusion list so you’re not wasting time trying to detect cars in the ocean.

Exclusion Regions:

OpenSpaceNet detect --model my_model.gbdxm --output output.geojson --image my_image.tif --exclude-region exclusion_zone.geojson

Depending on the network you’ve used to create your model, there can be drastic differences in how it utilizes the GPU. The DeepCore SDK was built to quickly add new state-of-art models from recent research. Because some of these models can be experimental, we’ve added features into OpenSpaceNet to help aid in the reliability of these experimental models. For instance, setting max-utilization to 5 will ensure that you are not using too much GPU memory which could cause your process to crash.

GPU Utilization:

OpenSpaceNet detect --model my_model.gbdxm --output output.geojson --image my_image.tif --max-utilization 5

We are always processing huge amounts of imagery, so GPU management is very important. By specifying a GPU we can guarantee that OpenSpaceNet will only use that specific GPU to process. The command line below will only run on GPU 1.

GPU Management:

CUDA_VISIBLE_DEVICES=1 OpenSpaceNet detect --model my_model.gbdxm --output output.shp --image my_image.tif

There are a TON of other options available to tweak with in OpenSpaceNet. If you would like to see all the available options, use the command line below.

OpenSpaceNet Help:

OpenSpaceNet --help

We hope that these examples will help you get started with using our powerful OpenSpaceNet tool. If you have any questions or interest in our tool please feel free to contact us here

No Comments

Add your comment