Download a subarea

Use GDAL'S VSI cURL feature to download a subarea of a Planet image


THIS FUNCTIONALITY HAS BEEN DEPRECATED

the following guide is for informational purposes only, and does not reflect the current state of Planet's platform.

Overview

This guide explains how to download a subarea of a Planet image, saving time, bandwidth and storage. We will use an exciting new feature of the GDAL library, VSI Curl, which queries a part of a GeoTIFF file using an HTTP Range request.

You will need,

To export your Planet API Key to your environment:

export PLANET_API_KEY=a3a64774d30c4749826b6be445489d3b # (not a real key)

You can find GDAL installation instructions here.

To install the Python libraries, do:

pip install retrying
pip install requests

Once installation is complete, you're ready to start with Step 1 below.

A note about Planet Imagery Product Compatability: this tutorial is compatable with all ItemTypes & Asset Types.

Activate a scene containing your Subarea

First, we will activate a scene of a stretch of agricultural land in Yuma, AZ, with the Planet API client.

planet data download --activate-only --item-type PSScene3Band --asset-type visual --string-in id 20161109_173041_0e0e --quiet

Activation will take a few minutes. Run the command above again until you see a URL in the 'location' element of the response.

A full-size Planet Scene of Agricultural land in Yuma, AZ

Create a GeoJSON file of your Subarea

Define the geometry of the subarea you'd like to download in GeoJSON format, by drawing it at geojson.io:

Save the GeoJSON to a file e.g. subarea.geojson,

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type":"Polygon",
        "coordinates":[
          [
             [
                -114.176423930378903,
                32.691933554346988
             ],
             [
                -114.176423930378903,
                32.685249521402788
             ],
             [
                -114.168019741897595,
                32.685249521402788
             ],
             [
                -114.168019741897595,
                32.691933554346988
             ],
             [
                -114.176423930378903,
                32.691933554346988
             ]
          ]
        ]
      }
    }
  ]
}

Download the Subarea

Next let's request a download URL for this image from the Planet Data API. Note, you must do this every time you wish to download your subarea, as these download URLs expire after 1 hour.

from osgeo import gdal
from requests.auth import HTTPBasicAuth
import os
import requests

item_id = "20161109_173041_0e0e"
item_type = "PSScene3Band"
asset_type = "visual"
item_url = 'https://api.planet.com/data/v1/item-types/{}/items/{}/assets'.format(item_type, item_id)

# Request a new download URL
result = requests.get(item_url, auth=HTTPBasicAuth(os.environ['PLANET_API_KEY'], ''))
download_url = result.json()[asset_type]['location']

Prefix the download URL with '/vsicurl/' to use the VSI Curl driver. Then call GDAL Warp, passing it an output file name, this URL, our subarea GeoJSON, a projection (in this case, the one used by GeoJSON.io), and 'cropToCutline = True'.

vsicurl_url = '/vsicurl/' + download_url
output_file = item_id + '_subarea.tif'

# GDAL Warp crops the image by our AOI, and saves it
gdal.Warp(output_file, vsicurl_url, dstSRS = 'EPSG:4326', cutlineDSName = 'subarea.geojson', cropToCutline = True)

Within a couple of seconds, you'll have an image of just the subarea in your directory.


Questions or comments about this guide? Join the conversation at Planet Community.