PLScenes (Planet Labs Scenes API)

(GDAL/OGR >= 2.0)

This driver can connect to Planet Labs Scenes API. GDAL/OGR must be built with Curl support in order for the PLScenes driver to be compiled.

The driver supports read-only operations to list scenes and their metadata as a vector layer per scene type ("ortho" for example). It can also access raster scenes.

Dataset name syntax

The minimal syntax to open a datasource is :

PLScenes:[options]

Additionnal optional parameters can be specified after the ':' sign. Currently the following one is supported :

api_key=value: To specify the Planet API KEY. It is mandatory, unless it is supplied through the open option API_KEY, or the configuration option PL_API_KEY.
scene=scene_id: To specify the scene ID, when accessing raster data. Optional for vector layer access.
product_type=value: To specify the product type: 'visual', 'analytic' or 'thumb' (for raster fetching). Default is "visual". Optional for vector layer access.

If several parameters are specified, they must be separated by a comma.

Open options

The following open options are available :

API_KEY=value: To specify the Planet API KEY.
SCENE=scene_id: To specify the scene ID, when accessing raster data. Optional for vector layer access.
PRODUCT_TYPE=value: To specify the product type: 'visual', 'analytic' or 'thumb (for raster fetching). Default is "visual". Optional for vector layer access.
RANDOM_ACCESS=YES/NO: Whether raster should be accessed in random access mode (but with potentially not optimal throughput). If NO, in-memory ingestion is done. Default is YES.

Configuration options

The following configuration options are available :

PL_API_KEY=value: To specify the Planet API KEY.

Attributes

The scene metadata are retrieved into the following feature fields for the "ortho" layer :

Name Type Description

id String Scene unique identifier.

acquired DateTime The time that image was taken in UTC.

camera.bit_depth Integer Bit depth with which the image was taken onboard the satellite. Currently 8 or 12.

camera.color_mode String The color mode of the image as taken by the satellite. Currently "RGB" or "Monochromatic".

camera.exposure_time Integer The exposure time in microseconds.

camera.gain Integer The analog gain with which the image was taken.

camera.tdi_pulses Integer The number of pulses used for time delay and integration on the CCD. Currently 0 (if TDI was not used), 4, 6, or 12.

cloud_cover.estimated Real The estimated percentage of the image covered by clouds. Decimal 0-100.

data.products.analytic.full String URL to download scene GeoTIFF of the "analytic" product.

data.products.visual.full String URL to download scene GeoTIFF of the "visual" product.

file_size Integer The size of the full image in bytes.

image_statistics.gsd Real The ground sample distance (distance between pixel centers measured on the ground) of the image in meters.

image_statistics.image_quality String Image quality category for scene. One of 'test', 'standard', or 'target'.

image_statistics.snr Real The estimated signal to noise ratio. Decimal > 0. Values greater than or equal to 50 are considered excellent quality. Values less than 50 and greater than or equal to 20 are considered adequate quality. Values less than 20 are considered poor quality.

links.full String URL to download scene GeoTIFF (same content as data.products.visual.full currently)

links.self String URL to scene information

links.square_thumbnail String URL to image thumbnail

links.thumbnail String Link to image square thumbnail

sat.alt Real The altitude of the satellite when the image was taken in kilometers.

sat.id String A unique identifier for the satellite that captured this image.

sat.lat Real The latitude of the satellite when the image was taken in degrees.

sat.lng Real The longitude of the satellite when the image was taken in degrees.

sat.off_nadir Real The angle off nadir in degrees at which the image was taken.

strip_id Real A unique float identifier for the set of images taken sequentially be the same satellite.

sun.altitude Real The altitude (angle above horizon) of the sun from the imaged location at the time of capture in degrees.

sun.azimuth Real The azimuth (angle clockwise from north) of the sun from the imaged location at the time of capture in degrees.

sun.local_time_of_day Real The local sun time at the imaged location at the time of capture (0-24).

For other layers / scene types, additional attributes may be retrieved.

Name	Type	Description
id	String	Scene unique identifier.
acquired	DateTime	The time that image was taken in UTC.
camera.bit_depth	Integer	Bit depth with which the image was taken onboard the satellite. Currently 8 or 12.
camera.color_mode	String	The color mode of the image as taken by the satellite. Currently "RGB" or "Monochromatic".
camera.exposure_time	Integer	The exposure time in microseconds.
camera.gain	Integer	The analog gain with which the image was taken.
camera.tdi_pulses	Integer	The number of pulses used for time delay and integration on the CCD. Currently 0 (if TDI was not used), 4, 6, or 12.
cloud_cover.estimated	Real	The estimated percentage of the image covered by clouds. Decimal 0-100.
data.products.analytic.full	String	URL to download scene GeoTIFF of the "analytic" product.
data.products.visual.full	String	URL to download scene GeoTIFF of the "visual" product.
file_size	Integer	The size of the full image in bytes.
image_statistics.gsd	Real	The ground sample distance (distance between pixel centers measured on the ground) of the image in meters.
image_statistics.image_quality	String	Image quality category for scene. One of 'test', 'standard', or 'target'.
image_statistics.snr	Real	The estimated signal to noise ratio. Decimal > 0. Values greater than or equal to 50 are considered excellent quality. Values less than 50 and greater than or equal to 20 are considered adequate quality. Values less than 20 are considered poor quality.
links.full	String	URL to download scene GeoTIFF (same content as data.products.visual.full currently)
links.self	String	URL to scene information
links.square_thumbnail	String	URL to image thumbnail
links.thumbnail	String	Link to image square thumbnail
sat.alt	Real	The altitude of the satellite when the image was taken in kilometers.
sat.id	String	A unique identifier for the satellite that captured this image.
sat.lat	Real	The latitude of the satellite when the image was taken in degrees.
sat.lng	Real	The longitude of the satellite when the image was taken in degrees.
sat.off_nadir	Real	The angle off nadir in degrees at which the image was taken.
strip_id	Real	A unique float identifier for the set of images taken sequentially be the same satellite.
sun.altitude	Real	The altitude (angle above horizon) of the sun from the imaged location at the time of capture in degrees.
sun.azimuth	Real	The azimuth (angle clockwise from north) of the sun from the imaged location at the time of capture in degrees.
sun.local_time_of_day	Real	The local sun time at the imaged location at the time of capture (0-24).

Geometry

The footprint of each scene is reported as a MultiPolygon with a longitude/latitude WGS84 coordinate system (EPSG:4326).

Filtering

The driver will forward any spatial filter set with SetSpatialFilter() to the server. It also makes the same for simple attribute filters set with SetAttributeFilter(). Note that not all attributes support all comparison operators. Refer to comparator column in Metadata properties

Paging

Features are retrieved from the server by chunks of 1000 by default (and this is the maximum value accepted by the server). This number can be altered with the PLSCENES_PAGE_SIZE configuration option.

Vector layer (scene metadata) examples

Listing all scenes available (with the rights of the account) :

ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value

ogrinfo -ro -al "PLScenes:api_key=some_value"

ogrinfo -ro -al "PLScenes:" --config PL_API_KEY some_value

Listing all scenes available under a point of (lat,lon)=(40,-100) :

ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -spat -100,40,-100,40

Listing all scenes available within a bounding box (lat,lon)=(40,-100) to (lat,lon)=(39,-99)

ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -spat -100,40,-99,39

Listing all scenes available matching critera :

ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -where "acquired >= '2015/03/26 00:00:00' AND \"cloud_cover.estimated\" < 10"

Raster access

Scenes and their thumbnails can be accessed as raster datasets, provided that the scene ID is specified with the 'scene' parameter / SCENE open option. The product type (visual, analytic or thumb) can be specified with the 'product_type' parameter / PRODUCT_TYPE open option. The scene id is the content of the value of the 'id' field of the features of the 'ortho' vector layer

This functionality is a conveniency wrapper of the API for fetching the scene GeoTIFF

Raster access examples

Displaying raster metadata :

gdalinfo "PLScenes:scene=scene_id,product_type=analytic" -oo API_KEY=some_value

gdalinfo "PLScenes:" -oo API_KEY=some_value -oo SCENE=scene_id -oo PRODUCT_TYPE=analytic

Converting/downloading a whole file:

gdal_translate "PLScenes:" -oo API_KEY=some_value -oo SCENE=scene_id \
                -oo PRODUCT_TYPE=analytic -oo RANDOM_ACCESS=NO out.tif