This driver can connect to Planet Labs Scenes v0/Catalog v1 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/catalog ("ortho" for example). It can also access raster scenes.
PLScenes:[options]
Additionnal optional parameters can be specified after the ':' sign. Currently the following one is supported :
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 the v1 API, the layer field definition is built dynamically from the catalog specification. The links to downloadable products are in asset_XXXXX_file attributes where XXXXX is the asset category id.
The details about the layer field description are given in the FIELDS_DESCRIPTION metadata item as a JSon serialized object. The keys are the OGR field names, and the value is an object that contains the definition of each field, with the following attributes :
{ "id":{ "description":"Identifier of this Item.", "type":"string", "src_field":"id", "server_queryable":true }, "self_link":{ "description":"RFC 3986 URI representing the canonical location of this object.", "type":"string", "src_field":"_links._self", "server_queryable":false }, "assets_link":{ "description":"RFC 3986 URI representing the canonical location of the ItemAssets subcollection.", "type":"string", "src_field":"_links.assets", "server_queryable":false }, "acquired":{ "description":"The RFC 3339 acquisition time of underlying image.", "format":"date-time", "type":"string", "src_field":"properties.acquired", "server_queryable":true }, "created":{ "description":"The RFC 3339 timestamp at which this Item was added to the Catalog.", "format":"date-time", "type":"string", "src_field":"properties.created", "server_queryable":true }, "black_fill":{ "description":"Ratio of image containing artificial black fill due to clipping to actual data.", "format":"float", "maximum":1.000000, "minimum":0.000000, "type":"number", "src_field":"properties.catalog::black_fill", "server_queryable":true }, "cloud_cover":{ "description":"Ratio of the image covered by clouds to that which is uncovered.", "format":"float", "maximum":1.000000, "minimum":0.000000, "type":"number", "src_field":"properties.catalog::cloud_cover", "server_queryable":true }, "grid_cell":{ "description":"The grid cell identifier of the gridded Item.", "type":"string", "src_field":"properties.catalog::grid_cell", "server_queryable":true }, "provider":{ "description":"Name of the imagery provider.", "enum":[ "planetscope", "rapideye", "landsat", "sentinel" ], "type":"string", "src_field":"properties.catalog::provider", "server_queryable":true }, "resolution":{ "description":"Pixel resolution of the Item image(s) in meters.", "format":"float", "minimum":0.000000, "type":"number", "src_field":"properties.catalog::resolution", "server_queryable":true }, "satellite_id":{ "description":"Globally unique identifier of the satellite that acquired the underlying image.", "type":"string", "src_field":"properties.catalog::satellite_id", "server_queryable":true }, "sun_azimuth":{ "description":"Angle from the True North to the Sun Vector projected on the horizontal plane in degrees.", "format":"float", "maximum":360.000000, "minimum":0.000000, "type":"number", "src_field":"properties.catalog::sun_azimuth", "server_queryable":true }, "sun_elevation":{ "description":"Elevation angle of the sun in degrees.", "format":"float", "maximum":90.000000, "minimum":0.000000, "type":"number", "src_field":"properties.catalog::sun_elevation", "server_queryable":true }, "usable_data":{ "description":"Ratio of the usable to unusable portion of the image due to cloud cover or black fill.", "format":"float", "maximum":1.000000, "minimum":0.000000, "type":"number", "src_field":"properties.catalog::usable_data", "server_queryable":true }, "view_angle":{ "description":"Spacecraft across-track off-nadir viewing angle used for imaging, in degrees with \"+\" being East and \"-\" being West.", "format":"float", "maximum":25.000000, "minimum":-25.000000, "type":"number", "src_field":"properties.catalog::view_angle", "server_queryable":true }, "asset_analytic_self_link":{ "description":"RFC 3986 URI representing the canonical location of this asset.", "type":"string", "src_field":"_embeds.assets.analytic._links._self", "server_queryable":false }, "asset_analytic_file":{ "description":"RFC 3986 URI representing a location that will either directly serve the underlying asset data, or redirect to a location that will. A client must never attempt to construct this URI, as only its behavior is governed by this specification, not its location. In the event that a 202 is returned from a GET request against this URI, the response's `X-Retry-After` header indicates how long the client should wait before reattempting the request.", "type":"string", "src_field":"_embeds.assets.analytic.file", "server_queryable":false }, "asset_analytic_mimetype":{ "description":"The MIME type of the underlying asset file.", "type":"string", "src_field":"_embeds.assets.analytic.mimetype", "server_queryable":false }, "asset_visual_self_link":{ "description":"RFC 3986 URI representing the canonical location of this asset.", "type":"string", "src_field":"_embeds.assets.visual._links._self", "server_queryable":false }, "asset_visual_file":{ "description":"RFC 3986 URI representing a location that will either directly serve the underlying asset data, or redirect to a location that will. A client must never attempt to construct this URI, as only its behavior is governed by this specification, not its location. In the event that a 202 is returned from a GET request against this URI, the response's `X-Retry-After` header indicates how long the client should wait before reattempting the request.", "type":"string", "src_field":"_embeds.assets.visual.file", "server_queryable":false }, "asset_visual_mimetype":{ "description":"The MIME type of the underlying asset file.", "type":"string", "src_field":"_embeds.assets.visual.mimetype", "server_queryable":false } }
ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_valueor
ogrinfo -ro -al "PLScenes:api_key=some_value"or
ogrinfo -ro -al "PLScenes:" --config PL_API_KEY some_value
ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -spat -100,40,-100,40
ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -spat -100,40,-99,39
ogrinfo -ro -al "PLScenes:" -oo API_KEY=some_value -where "acquired >= '2015/03/26 00:00:00' AND \"cloud_cover.estimated\" < 10"
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 convenience wrapper of the API for fetching the scene GeoTIFF
For API v1, the CATALOG open option must be specified. If the product is not already cached on the server, it will be asynchronously generated and the open attempt will return an error. Further retries will be needed.
gdalinfo "PLScenes:scene=scene_id,product_type=analytic" -oo API_KEY=some_valueor
gdalinfo "PLScenes:" -oo API_KEY=some_value -oo SCENE=scene_id -oo PRODUCT_TYPE=analytic
gdal_translate "PLScenes:" -oo API_KEY=some_value -oo SCENE=scene_id \ -oo PRODUCT_TYPE=analytic -oo RANDOM_ACCESS=NO out.tif