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 4096 x 2160 pixels or the equivalent of 135 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 8,847,360 pixels (e.g. 4096 x 2160) or 135 tiles.

  1. 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.

  2. 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 (135).  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.

  3. 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: 8,847,360 pixels or 135 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-high
Wide area data collected with Condor (20cm GSD)

bluesky-high-europe
Wide area data collected with Condor in Europe (20cm 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

The height parameter is only available for requests using xcoordinate / ycoordinates.

zoom

Key-Value-Pair

Integer

standard mercator tile zoom level from 1 to 21.

zoom=20

The zoom parameter is mandatory for requests using xcoordinate / ycoordinates, optional for requests using wkt.

  • Polygon

wkt

Key-Value-Pair

String

The “well-known text” field is used to define a 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))

More info on well-known text (wkt) in External Resources

Optional Parameters:

zoom

Key-Value-Pair

Integer

standard mercator tile zoom level from 1 to 21.

zoom=20

The zoom parameter is mandatory for requests using xcoordinate / ycoordinates, optional for requests using wkt.

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

The crop parameter is only available for requests using the wkt parameter

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-high: aoi=USUSCON2001

bluesky-high-europe: aoi=EUEUCON2001

graysky-g: aoi=USMSCOL1902

graysky: aoi=us-la-neworleans-tornado-2022

The available AOI(s) for a point or polygon can be determined using the OrthoCoverage service.

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-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

The available ChildAOI(s) for a point or polygon can be determined using the OrthoCoverage service.

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

format=image/png

By default, the layers of bluesky-ultra and high return png, and bluesky-ultra-g return jpeg. To receive an image with transparent background, use format=image/png. 

startDate

Alias: initDate

Key-Value-Pair

String

No images taken before this date will be delivered.

startDate=2019-01-01T00:00:01+00:00

Format: ISO 8601 ("yyyy-MM-dd'T'HH:mm:ss")

endDate

Key-Value-Pair

String

No images collected after this date will be delivered.

endDate=2021-01-01T00:00:01+00:00

Format: ISO 8601 ("yyyy-MM-dd'T'HH:mm:ss")

returnTransparent

Key Value Pair

Boolean

The flag that determines what to return along with a “404 - Imagery not found” response.

True - A completely transparent .png file.

False - message: “Information not found”

returnTransparent=True

This parameter is only available when format=png.

If any imagery is available within the tile, the non-imagery pixels will be either black (format=jpeg) or transparent (format=png).

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.

rgb - Default - Red, green and blue bands
nir - Near-infrared band (partially unavailable for bluesky-ultra-g or graysky-g)

renderingRule=rgb

nir is not available for all imagery in the bluesky-ultra-g or graysky-g layers due to those layers having imagery from multiple collection sensors, of which only one collected NIR imagery.

apply_coverage_mask

Key Value Pair

String

Applies mask for transparency when true, removes black pixels when false

true

false

apply_coverage_mask=false

 


Examples

These examples cover the three ways to specify an image as discussed under the Technical Details section.

  1. 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}

Parameter

Value

Parameter

Value

layer

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}

Parameter

Value

Parameter

Value

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}

Parameter

Value

Parameter

Value

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))

zoom

19

startDate

2021-02-09T00:00:01+00:00

endDate

2021-03-16T23:59:59+00:00

token

{token}

Image:


External Resources

Note, the following resources are external to Vexcel and may change without prior notice.