DroneDeploy

Map Processing API

This page describe how to use the DroneDeploy map processing engine as a service

Generate maps from photos via our API

You can produce high quality 3D maps from your source image sets without building your own photogrammetry pipeline. We'll take you through setting up a plan and image transfer object, adding images, running exports, and accessing the generated tiles.

First you will need an API Key

More information is also available on our Data API.

Create a "Plan"

The Plan object is the central element to much of the DroneDeploy process. It is the container for all of the critical information about your map, and is required for many of the other operations you'll be performing with the API. Fortunately, setting up a plan with default values is easy.

/v2/plans

curl -H "Content-Type: application/json" -X POST -d '{"name":"My Plan"}' "https://public-api.dronedeploy.com/v2/plans?api_key=f78b0a0d66274fd5a8684c49deb9d83d"
{"id": "58b0490c95b03d000114a881"}

It is best to name your plan something unique, although it is not required. Each plan is assigned a unique identifier within the DroneDeploy system. That value is returned as the result of the POST operation.

Once a plan has been created, it is time to add some source imagery to the plan.

Create an "Image Transfer"

The Image Transfer object is the way API clients can indicate which source imagery should be used for a given plan. Once an image transfer object is created, the indicated URL is fetched and the photogrammetry process begins.

While an API client can specify a list of individual images for processing, it is a best practice to create a ZIP archive of all necessary imagery beforehand and specify the compressed file as the URL. This can help ensure completeness of the operation and should reduce overall time taken to fetch the source imagery.

We support a few various options for file types. For map processing, input type map_source_image, we support jpeg, png, and tiffs for unprocessed and tiffs for preprocessed maps. We also support zip archives of these files. If a zip archive is supplied, the archive will be opened and the imagery files uploaded for map processing. Input types image, video, and pano refer to unprocessed assets and will not be including in the photogrammetry processing, but instead stored as stored_assets on the associated plan.

/v2/image_transfer

curl -H "Content-Type: application/json" -X POST -d '{"plan_id":"58b0490c95b03d000114a881", "tansport": {"type": "https"}, "inputs": [{"location": "https://www.dropbox.com/s/nc2okgk83k439pj/dropbox_example.zip?dl=1", "type": "map_source_image"}]}' "https://public-api.dronedeploy.com/v2/image_transfer?api_key=f78b0a0d66274fd5a8684c49deb9d83d"
{
  "status": "New", 
  "transport": {"type": "https"},
  "inputs": [
    {"location": "https://www.dropbox.com/s/nc2okgk83k439pj/dropbox_example.zip?dl=1", "type": "map_source_image"}
  ], 
  "plan_id": "58b0490c95b03d000114a881", 
  "failure_info": {}, 
  "id": "58b056b795b03d000114a882", 
  "run_info": {}, 
  "date_complete": null, 
  "date_started": null, 
  "type": "unprocessed", 
  "date_creation": 1487951543526
}

Image Transfers also support the s3 transport type. This allows direct copying of files between your S3 buckets and our, saving network access costs and time. Specify the s3 transport with "transport": {"type": "s3"}.

In order to support s3 transport you will need to add the following bucket policy to the bucket that want to copy files from.

    {
        "Version": "2012-10-17",
        "Statement": [
	    {
                "Sid": "DroneDeploy Direct Copy Policy",
                "Effect": "Allow",
                "Principal": {
                    "AWS": ["arn:aws:iam::426387074071:user/image-transfer"]
                },
                "Action": [
                    "s3:GetObject"
                ],
                "Resource": [
                    "arn:aws:s3:::SOURCE/*"
                ]
            }
        ]
    }

Be sure to replace SOURCE with the name of your bucket.

You will also need to contact support and provide the name of the bucket(s) you are granting access to so that we can update our IAM user policy.

Monitor progress

Once the Image Transfer object is received, the DroneDeploy Map Engine will fetch the indicated files based on the account type priority settings. Once the files have been fetched, decompressed (if necessary) and validated, map processing will begin.

You can monitor this process by observing the response from the Image_Transfer, then the Plan object. The status will show "Complete" when the download and photogrammetry processes have concluded respectively.

/v2/image_transfer/{id}

To check the status of your image transfer, request the image_transfer API with the ID you were returned when you posted to the endpoint.

curl "https://public-api.dronedeploy.com/v2/image_transfer/58be0da47915d90001962385?api_key=f78b0a0d66274fd5a8684c49deb9d83d"
{"status": "new", "transport": {"type": "https"}, "inputs": [{"location": "https://dl.dropboxusercontent.com/1/view/asdaafasdasd/ImageTransfer/roofofDD23.zip", "type": "map_source_image"}], "plan_id": "58be0d647915d9000196237b", "date_creation": 1488850340459, "date_complete": null, "date_started": null, "type": "unprocessed", "id": "58be0da47915d90001962385"}

/v2/plans/{id}?embed=stored_asset([download_path,asset_type])

To check the status of your map processing, request the Plan API with the PlanID. The ?embed=stored_asset([download_path,asset_type]) ensures that any stored, unprocessed, assets associated with the plan will be returned in the response body.

curl "https://public-api.dronedeploy.com/v2/plans/58b0490c95b03d000114a881?api_key=f78b0a0d66274fd5a8684c49deb9d83d&embed=stored_asset([download_path,asset_type])"
{
    "date_creation": 1487948044752,
    "geometry": [],
    "id": "58b0490c95b03d000114a881",
    "image_count": 1,
    "latest_image_transfer_id": "58b056b795b03d000114a882",
    "latest_started_map": {
        "user_status": "Processing"
    },
    "location": {},
    "log": "1487948044_APIGENERATED",
    "name": "My Plan",
    "stored_assets": []
}

What's Next

Now you've generated a map, you may want to embed the map tiles in your application or take measurements:

Tile Template API
Measurements API

Map Processing API

This page describe how to use the DroneDeploy map processing engine as a service