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

Parameter	Parameter Type	Data Type	Description	Example Format	Notes
Mandatory:
`layer`	Ordered REST 1st or key-value-pair	String	Layer of the requested image. `bluesky-ultra-g` Urban data collected by Geomni (7.5 GSD) `bluesky-ultra` Urban data collected with Osprey (7.5cm GSD) `bluesky-ultra-europe` Urban data collected with Osprey in Europe (7.5 GSD) `bluesky-ultra-oceania` Urban data collected with Osprey in Oceania (7.5 GSD) `bluesky-ultra-japan` Urban data collected with Osprey in Japan (7.5 GSD) `urban-r` Urban data collected with Condor (7.5 GSD) `bluesky-high` Wide area data collected with Condor (15cm GSD) `bluesky-high-europe` Wide area data collected with Condor in Europe (15cm GSD) `graysky-g` Gray Sky events collected by Geomni `graysky` Gray Sky events collected with Ultracam sensors	`/bluesky-ultra-g/`
`EPSG`	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.	`EPSG=4326`
`token`	Key-Value-Pair	String	Authentication token received from Login service. Specific to each individual user.	`token={token}`	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.
Lat/Lon Coordinates
`xcoordinate`	Key-Value-Pair	Double	The longitudinal decimal degree coordinate for the center of the desired image, represented by the EPSG projection defined by the `EPSG` parameter.	`xcoordinate=-93.4251`	More info on Decimal Degrees in External Resources
`ycoordinate`	Key-Value-Pair	Double	The latitudinal decimal degree coordinate for the center of the desired image, represented by the EPSG projection defined by the `EPSG` parameter.	`ycoordinate=44.9186`
`width`	Key-Value-Pair	Integer	the width of the returned image in pixels.	`width=600`	The `width` parameter is only available for requests using `xcoordinate` / `ycoordinates`.
`height`	Key-Value-Pair	Integer	the height of the returned image in pixels.	`height=400`
`zoom`	Key-Value-Pair	Integer	standard mercator tile zoom level from 1 to 21.	`zoom=20`
Polygon
`wkt`	Key-Value-Pair	String	The “well-known text” field is used to define a point, polygon or multi-polygon around the desired area.	`wkt=POLYGON((-93.41947148592193 44.91507523063691,-93.4185112550946 44.91507523063691,-93.4185112550946 44.91431925758581,-93.41947148592193 44.91431925758581,-93.41947148592193 44.91507523063691))`
Optional Parameters:
`zoom`	Key-Value-Pair	Integer	standard mercator tile zoom level from 1 to 21.	`zoom=20`
`year`	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.	`year=2021`
`crop`	Key-Value-Pair	String	The method with which to crop the returned images based on the input `wkt` parameter. `crop`- Default - Clips the image(s) to the minimum bounding rectangle of the `wkt` polygon. `exact` - Clips the image(s) to the exact shape of the `wkt` polygon.	`crop=crop`
`AOI`	Key-Value-Pair	String	The identifier of the Area of Interest (AOI) which contains the desired imagery.	`AOI=` bluesky-ultra-g: `aoi=us-al-tuscaloosa_leica-2020` bluesky-ultra: `aoi=us-az-avondale-2021` bluesky-ultra-europe: `aoi=it-62-rome-2020` bluesky-ultra-oceania: `aoi=au-qld-sunshinecoast-2019` bluesky-ultra-japan: `aoi=jp-20-matsumoto-2022` urban-r: `aoi=us-ok-oklahomacity_rf01-2023` bluesky-high: `aoi=USUSCON2001` bluesky-high-europe: `aoi=EUEUCON2001` graysky-g: `aoi=USMSCOL1902` graysky: `aoi=us-la-neworleans-tornado-2022`
`ChildAOI`	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 `AOI` parameter in cases where the AOI contains several smaller collection regions; for many Blue Sky AOIs there is no child AOI. This parameter can be especially useful for Gray Sky events.	`ChildAOI=` bluesky-ultra-g: `ChildAOI=us-al-tuscaloosa_leica-2020` bluesky-ultra: `ChildAOI=us-az-avondale-2021` bluesky-ultra-europe: `ChildAOI=it-62-rome-2020` bluesky-ultra-oceania: `ChildAOI=au-qld-sunshinecoast-2019` bluesky-ultra-japan: `ChildAOI=jp-20-matsumoto-2022` urban-r: `ChildAOI=us-ok-oklahomacity_rf01-2023` bluesky-high: `ChildAOI=n33w87-us-al-tuscaloosa-2019` bluesky-high-europe: `ChildAOI=n41e13-it-lt-aprilia-2020` graysky-g: `ChildAOI=190226/USMSCOLDMC` graysky: `ChildAOI=graydata-363`
`format`	Key-Value-Pair	String	The image file format. `png` - Default for layers bluesky-high and bluesky-ultra. Capable of returning a transparent background where imagery does not exist. `jpeg` - Default for layer bluesky-ultra-g `tiff` - Georeferenced tiff	`format=image/png`
`dst_height`	Key Value Pair	Integer	The combination of `dst_height` and `dst_width` is used to define the size and aspect ratio of a destination frame. The input geometry will be centered within the destination frame with additional imagery extending either vertically or horizontally to fill the destination frame if necessary.	`dst_height=600`
`dst_width`	Key Value Pair	Integer	The combination of `dst_height` and `dst_width` is used to define the size and aspect ratio of a destination frame. The input geometry will be centered within the destination frame with additional imagery extending either vertically or horizontally to fill the destination frame if necessary.	`dst_width=800`
`startDate` Alias: `initDate`	Key-Value-Pair	String	No images taken before this date will be delivered.	`startDate=2019-01-01T00:00:01+00:00`
`endDate`	Key-Value-Pair	String	No images collected after this date will be delivered.	`endDate=2021-01-01T00:00:01+00:00`
`returnTransparent`	Key Value Pair	Boolean	The flag that determines what to return along with a “404 - Imagery not found” response.	`returnTransparent=True`
`rotatedNorth`	Key Value Pair	string	Determines the rotation of the image: `no` - default - Rotated to orientation of collection `yes` - North-orientated.	`rotatedNorth=yes`
`renderingRule`	Key-Value-Pair	String	The color band rendering of the tiles.	`renderingRule=rgb`
`apply_coverage_mask`	Key Value Pair	String	Applies mask for transparency when true, removes black pixels when false	`apply_coverage_mask=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 line
outlineColor - The color for the polygon’s exterior line (RGB format)
fillColor - The color for the polygon’s fill
drawingPointList - 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 labels
fontColor - 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: https://en.wikipedia.org/wiki/EPSG_Geodetic_Parameter_Dataset
Well-known text (wkt): https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry
Decimal Degrees: https://en.wikipedia.org/wiki/Decimal_degrees

Vexcel API Documentation

ExtractOrthoImages - v1.4

Introduction

Technical Details

Base URL

Parameters

Optional - Drawing Elements (POST Request)

Examples

See Also

External Resources