frmt_plmosaic.html 6.97 KB
Newer Older
xuebingbing's avatar
xuebingbing committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
<html>
<head>
<title>PLMosaic (Planet Labs Mosaics API)</title>
</head>

<body bgcolor="#ffffff">

<h1>PLMosaic (Planet Labs Mosaics API)</h1>

(GDAL/OGR &gt;= 2.0)<p>

This driver can connect to Planet Labs Mosaics API.
GDAL/OGR must be built with Curl support in order for the
PLMosaic driver to be compiled.<p>

The driver supports listing mosaics and reading them.
Mosaics are accessed at their highest resolution. Mosaics are typically composed of quads of
4096x4096 pixels.<p>

For mosaics of type Byte, overviews are available by using the tile API. For other
data types, there is no support for overviews, so requests that involve downsampling may
take a long time to complete.<p>

<h2>Dataset name syntax</h2>

The minimal syntax to open a datasource is : <pre>PLMosaic:[options]</pre><p>

Additional optional parameters can be specified after the ':' sign.
Currently the following one is supported :<p>

<ul>
<li> <b>api_key</b>=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.</li>
<li> <b>mosaic</b>=mosaic_name: To specify the mosaic name.</li>
<li><b>cache_path</b>=path: To specify the path to a directory where cached
quads (and tiles) are stored. A plmosaic_cache/{mosaic_name} subdirectory will be created
under that path. The empty string can be used to disable any disk caching.</li>
<li><b>trust_cache</b>=YES/NO: Whether already cached quads should be reused directly,
without prior checking if the server has a more recent version. Note:
this only applies to quads, and not tiles. Default is NO.</li>
<li><b>use_tiles</b>=YES/NO: Whether to use the tile API to access full
resolution data, instead of downloading quads. Only apply for Byte mosaics. Default is NO.</li>
</ul>

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

<p>If no mosaic parameter is supplied, the list of available mosaics will be
returned as subdatasets. If only one mosaic is available, it will be directly
opened.</p>

<h2>Open options</h2>

<p>The following open options are available : API_KEY, MOSAIC, CACHE_PATH,
TRUST_CACHE and USE_TILES. They have the same semantics as the above
describe parameters of same name.</p>

<h2>Configuration options</h2>

The following configuration options are available :
<ul>
<li><b>PL_API_KEY</b>=value: To specify the Planet API key.</li>
</ul>

<h2>Location information</h2>

<p>
The special <i>Pixel_{x}_{y}</i> metadata item of the <i>LocationInfo</i> metadata domain,
where x is the column and y is the line in the mosaic, can be queried to get
information about the scenes that compose the underneath quad. This is
the syntax used by the gdallocationinfo utility
(see <a href="https://trac.osgeo.org/gdal/wiki/rfc32_gdallocationinfo">RFC 32</a>)
</p>

<p>Below an example of the return :
<pre>
&lt;LocationInfo&gt;
  &lt;Scenes&gt;
    &lt;Scene&gt;
      &lt;link&gt;https://api.planet.com/data/v1/item-types/PSScene3Band/items/20161025_000336_0e19&lt;/link&gt;
    &lt;/Scene&gt;
    &lt;Scene&gt;
      &lt;link&gt;https://api.planet.com/data/v1/item-types/PSScene3Band/items/20161119_000453_0e14&lt;/link&gt;
    &lt;/Scene&gt;
    &lt;Scene&gt;
      &lt;link&gt;https://api.planet.com/data/v1/item-types/PSScene3Band/items/20161010_000309_0e26&lt;/link&gt;
    &lt;/Scene&gt;
    &lt;Scene&gt;
      &lt;link&gt;https://api.planet.com/data/v1/item-types/PSScene3Band/items/20161119_000452_0e14&lt;/link&gt;
    &lt;/Scene&gt;
  &lt;/Scenes&gt;
&lt;/LocationInfo&gt;
</pre>
</p>

<h3>Examples</h3>

<li> Listing all mosaics available (with the rights of the account) :
<pre>
gdalinfo "PLMosaic:" -oo API_KEY=some_value
</pre>
or
<pre>
gdalinfo "PLMosaic:api_key=some_value"
</pre>
or
<pre>
gdalinfo "PLMosaic:" --config PL_API_KEY some_value
</pre>

returns (in case of multiple mosaics):

<pre>
Driver: PLMOSAIC/Planet Labs Mosaics API
Files: none associated
Size is 512, 512
Coordinate System is `'
Image Structure Metadata:
  INTERLEAVE=PIXEL
Subdatasets:
  SUBDATASET_1_NAME=PLMOSAIC:mosaic=global_quarterly_2017q1_mosaic
  SUBDATASET_1_DESC=Mosaic global_quarterly_2017q1_mosaic
  ...
Corner Coordinates:
Upper Left  (    0.0,    0.0)
Lower Left  (    0.0,  512.0)
Upper Right (  512.0,    0.0)
Lower Right (  512.0,  512.0)
Center      (  256.0,  256.0)
</pre>


<li> Open a particular mosaic :
<pre>
gdalinfo "PLMosaic:mosaic=global_quarterly_2017q1_mosaic" -oo API_KEY=some_value
</pre>

returns:
<pre>
Driver: PLMOSAIC/Planet Labs Mosaics API
Files: none associated
Size is 8388608, 4427776
Coordinate System is:
PROJCS["WGS 84 / Pseudo-Mercator",
    GEOGCS["WGS 84",
        DATUM["WGS_1984",
            SPHEROID["WGS 84",6378137,298.257223563,
                AUTHORITY["EPSG","7030"]],
            AUTHORITY["EPSG","6326"]],
        PRIMEM["Greenwich",0,
            AUTHORITY["EPSG","8901"]],
        UNIT["degree",0.0174532925199433,
            AUTHORITY["EPSG","9122"]],
        AUTHORITY["EPSG","4326"]],
    PROJECTION["Mercator_1SP"],
    PARAMETER["central_meridian",0],
    PARAMETER["scale_factor",1],
    PARAMETER["false_easting",0],
    PARAMETER["false_northing",0],
    UNIT["metre",1,
        AUTHORITY["EPSG","9001"]],
    AXIS["X",EAST],
    AXIS["Y",NORTH],
    EXTENSION["PROJ4","+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs"],
    AUTHORITY["EPSG","3857"]]
Origin = (-20037508.342789243906736,13384429.400847502052784)
Pixel Size = (4.777314267823516,-4.777314267823516)
Metadata:
  FIRST_ACQUIRED=2017-01-01T00:00:00.000Z
  LAST_ACQUIRED=2017-04-01T00:00:00.000Z
  NAME=global_quarterly_2017q1_mosaic
Image Structure Metadata:
  INTERLEAVE=PIXEL
Corner Coordinates:
Upper Left  (-20037508.343,13384429.401) (180d 0' 0.00"W, 76d 0'57.94"N)
Lower Left  (-20037508.343,-7768448.059) (180d 0' 0.00"W, 57d 2'26.63"S)
Upper Right (20037508.343,13384429.401) (180d 0' 0.00"E, 76d 0'57.94"N)
Lower Right (20037508.343,-7768448.059) (180d 0' 0.00"E, 57d 2'26.63"S)
Center      (       0.000, 2807990.671) (  0d 0' 0.01"E, 24d26'49.74"N)
Band 1 Block=256x256 Type=Byte, ColorInterp=Red
  Overviews: 4194304x4194304, ..., 256x256
  Mask Flags: PER_DATASET ALPHA
  Overviews of mask band: Overviews: 4194304x4194304, ..., 256x256
Band 2 Block=256x256 Type=Byte, ColorInterp=Green
  Overviews: 4194304x4194304, ..., 256x256
  Mask Flags: PER_DATASET ALPHA
  Overviews of mask band: Overviews: 4194304x4194304, ..., 256x256
Band 3 Block=256x256 Type=Byte, ColorInterp=Blue
  Overviews: 4194304x4194304, ..., 256x256
  Mask Flags: PER_DATASET ALPHA
  Overviews of mask band: Overviews: 4194304x4194304, ..., 256x256
Band 4 Block=256x256 Type=Byte, ColorInterp=Alpha
  Overviews: 4194304x4194304, ..., 256x256
</pre>


<h2>See Also</h2>

<ul>
<li> <a href="https://docs.planet.com/reference#basemaps-and-mosaics">Documentation of Planet Mosaics API</a><p>
<li> <a href="https://docs.planet.com/docs/api-mechanics#section-authentication">API Authentication</a><p>
<li> <a href="drv_plscenes.html">Vector PLScenes / Planet Scenes API driver</a><p>
</ul>

</body>
</html>