ExtractOrthoImages - v1.4
Introduction
This service returns a piece of imagery as a JPG or PNG, cut from the seamless orthomosaic. The same imagery you can access via GetOrthoImageTiles is used to create the returned image. ExtractOrthoImages saves you the work of making multiple API calls to GetOrthoImageTiles for individual tiles, stitching them together into a large bitmap, and cropping it to your spec. With a single API call you can get back a static map image matching your specification.
Note: the maximum size for a returned image is 67,108,864 pixels or the equivalent of 1,024 individual tiles. If your request results in an image exceeding these limits, an error is returned.
Technical Details
You can use the OrthoCoverage service to determine where ortho coverage exists. This allows you to know if a call to ExtractOrthoImages will succeed or fail based on image availability.
USE CASES
All use cases will ensure that imagery will not exceed either 67,108,864 pixels (e.g., 4096 x 16384) or 1,024 tiles.
xcoordinate + ycoordinate + zoom + width + height: This is the most common use of the service. Here you pass in a coordinate where the image will be centered and a standard zoom level. You also pass in the width and height in Pixels of the image you want returned.
wkt: Here you pass a polygon in the WKT parameter that you want covered by the returned image. The service will calculate the deepest zoom level that covers the polygon with less than the maximum number of tiles (1,024). The resulting bitmap will be fit to the minimum bounding rectangle (or MBR) for the polygon that was passed in the WKT parameter. Note that the Pixel dimensions of the resulting image are also determined by the service and cannot be specified.
wkt + zoom: This is very similar to the previous case, but instead of the system selecting the optimal Zoom level, you specify it with the Zoom parameter. This allows you to scale the image (shown below under examples).
Output Tile Specifications:
8-bit depth
3-band (RGB or NIR)
7.5 or 20 cm centimeter resolution (layer dependent)
Image format: JPEG or PNG
Blue Sky and Gray Sky imagery available
Maximum size: 67,108,864 pixels or 1,024 tiles
Base URL
This service will answer to requests on following URLs:
Lat/Lon Coordinate Point
https://api.gic.org/images/ExtractOrthoImages?layer={layer}&epsg={epsg}&xcoordinate={xcoordinate}&ycoordinate={ycoordinate}&width={width}&height={height}&zoom={zoom}&token={token}
wkt Polygon Area
https://api.gic.org/images/ExtractOrthoImages?layer={layer}&epsg={epsg}&wkt={wkt}&token={token}
Parameters
Parameter | Parameter Type | Data Type | Description | Example Format | Notes |
---|---|---|---|---|---|
Mandatory: | |||||
| Ordered REST 1st or key-value-pair | String | Layer of the requested image.
Urban data collected with Osprey in Japan (7.5 GSD)
Urban data collected with Condor (7.5 GSD)
|
|
|
| Key-Value-Pair | Integer | ESPG code that determines the projection of the coordinates provided. A valid example would be 4326 for geographical latitude-longitude coordinates. |
|
|
| Key-Value-Pair | String | Authentication token received from Login service. Specific to each individual user. |
| Use the Authenticate Service to receive a token. |
Mandatory - Method of defining area: Lat/Lon Coordinates or Polygon. Only one method can be used per URL call. | |||||
| |||||
| Key-Value-Pair | Double | The longitudinal decimal degree coordinate for the center of the desired image, represented by the EPSG projection defined by the |
| More info on Decimal Degrees in External Resources |
| Key-Value-Pair | Double | The latitudinal decimal degree coordinate for the center of the desired image, represented by the EPSG projection defined by the |
|
|
| Key-Value-Pair | Integer | the width of the returned image in pixels. |
| The |
| Key-Value-Pair | Integer | the height of the returned image in pixels. |
| |
| Key-Value-Pair | Integer | standard mercator tile zoom level from 1 to 21. |
| |
| |||||
| Key-Value-Pair | String | The “well-known text” field is used to define a point, polygon or multi-polygon around the desired area. |
| |
Optional Parameters: | |||||
| Key-Value-Pair | Integer | standard mercator tile zoom level from 1 to 21. |
| |
| Key-Value-Pair | String | the 4-digit year of the collection to be used in creating the image. if there are more than 1 collections in the year, the most recent collection is used. |
| |
| Key-Value-Pair | String | The method with which to crop the returned images based on the input
|
| |
| Key-Value-Pair | String | The identifier of the Area of Interest (AOI) which contains the desired imagery. |
bluesky-ultra-g: bluesky-ultra: bluesky-ultra-europe: bluesky-ultra-oceania: bluesky-ultra-japan: urban-r: bluesky-high: bluesky-high-europe: graysky-g: graysky: | |
| Key-Value-Pair | String | The identifier of the child Area of Interest (AOI) which contains the desired imagery. This parameter can only be used in combination with the |
bluesky-ultra-g: bluesky-ultra: bluesky-ultra-europe: bluesky-ultra-oceania: bluesky-ultra-japan: urban-r: bluesky-high: bluesky-high-europe: graysky-g: graysky: | |
| Key-Value-Pair | String | The image file format.
|
| |
| Key Value Pair | Integer | The combination of |
|
|
| Key Value Pair | Integer | The combination of |
|
|
Alias: | Key-Value-Pair | String | No images taken before this date will be delivered. |
| |
| Key-Value-Pair | String | No images collected after this date will be delivered. |
| |
| Key Value Pair | Boolean | The flag that determines what to return along with a “404 - Imagery not found” response. |
| |
| Key Value Pair | string | Determines the rotation of the image:
|
|
|
| Key-Value-Pair | String | The color band rendering of the tiles. |
| |
| Key Value Pair | String | Applies mask for transparency when true, removes black pixels when false |
|
|
Optional - Drawing Elements (POST Request)
The ExtractOrthoImages service allows for the inclusion of custom drawing elements using a POST request. A POST request takes typical REST parameters (defined within the URL) but adds JSON elements in the body of the POST call to define the drawing elements.
Drawing Element Parameters
drawingPolygon
- The polygon to be draw in WKT format (The EPSG has to be the same EPSG that is in the head of the petition)lineWidth
- The width for the polygon’s exterior lineoutlineColor
- The color for the polygon’s exterior line (RGB format)fillColor
- The color for the polygon’s filldrawingPointList
- An object list of point(s) and associated label(s)point
- The point coordinates in latitude and longitude (decimal degrees).label
- The custom label for each point.
fontSize
- Font point size for labelsfontColor
- Font color for labels (RGB color)fontType
- Font typeface (Options: Monospaced, SansSerif or Serif)
JSON format:
{
"drawingPolygon": "[polygon wkt]",
"lineWidth": "[linewidth]",
"outlineColor": "[rgb]",
"fillColor": "[rgb]",
"drawingPointList": [
{
"point": "[point wkt]",
"label": "[custom text]"
},
{
"point": "[point wkt]",
"label": "[custom text]"
}
],
"fontSize": "[font point size]",
"fontColor": "[rgb]",
"fontType": "[font typeface]"
}
Examples
These examples cover the three ways to specify an image as discussed under the Technical Details section.
xcoordinate + ycoordinate + zoom + width + height
The Atomium - Brussels, Belgium - Demonstrating the ycoordinate
, xcoordinate
,layer
, width
and height
parameters
REST URL:
https://api.gic.org/images/ExtractOrthoImages/bluesky-high-europe?ycoordinate=50.894916&xcoordinate=4.340991&zoom=17&width=600&height=400&EPSG=4326&token={token}
Image:
________________________________________________________________________________________
2. wkt
Fort McHenry National Monument and Historic Shrine - Baltimore, MD - Demonstrating the epsg
, wkt
,zoom
, format
, AOI
and renderingRule
parameters
REST URL:
https://api.gic.org/images/ExtractOrthoImages?layer=bluesky-ultra&epsg=4326&wkt=POLYGON((-76.580924 39.263944, -76.578685 39.263938, -76.578682 39.262136, -76.580924 39.262134, -76.580924 39.263944))&format=image/png&AOI=us-md-baltimore-2021&renderingRule=nir&token={token}
Image:
________________________________________________________________________________________
3. wkt + zoom
Shrine of Remembrance - Melbourne, Australia - Demonstrating the zoom
, startDate
, and endDate
parameters
REST URL:
https://api.gic.org/images/ExtractOrthoImages?zoom=19&layer=bluesky-ultra-oceania&epsg=4326&wkt=POLYGON ((144.972431 -37.830084, 144.973944 -37.829724, 144.974269 -37.830955, 144.973075 -37.831252, 144.972431 -37.830084))&startDate=2021-02-09T00:00:01+00:00&endDate=2021-03-16T23:59:59+00:00&token={token}
Image:
External Resources
EPSG Codes: EPSG Geodetic Parameter Dataset
Well-known text (wkt): Well-known text representation of geometry
Decimal Degrees: Decimal degrees
Need help? Create a support ticket | support@vexcelgroup.com