/
ExtractNIRImages Service - v1.4

ExtractNIRImages Service - v1.4


Introduction

The ExtractNIRImages service will take a point or polygon and return the near-infrared (NIR) band within one or more color-shifted near-infrared (CIR) images, depending on the parameters of the request. Because the near-infrared band is outside of the visible spectrum, it is necessary to represent the near-infrared band using one of the visible spectrum colors (red, green or blue) using color-shifting. The resulting color-infrared (CIR) image represents the infrared, red and green (IRG) bands as:

  • near-infrared band as red

  • red band as green

  • green band as blue.

  • blue band is not returned

Despite being displayed as red, the near-infrared band contains accurate NIR data and can be used for many applications, including:

  • See through smoke (in combination with dynamic range processing)

  • Normalized difference vegetation indexing (NDVI)

  • Analyze agricultural fields (e.g. growth rate, irrigation/fertilizer use)

  • Classify land use (vegetated, non-vegetated, water, etc.)

  • Disaster assessment (identify living/dead vegetation)

 


Technical Details

The ExtractNIRImages service is accessed by specifying the point (latitude and longitude) or polygon bounding box (well-known-text). Depending on parameters, this service will return the whole image or a portion of the image. The portion of the image is dimensioned either by request parameters width and height and centered on the requested point when using the xcoordinate and ycoordinate or by the request parameter crop when using the wtk parameter. 

 

Output Image Specifications:

  • 8-bit depth

  • 7.5 or 20 cm centimeter resolution (layer dependent)

  • CIR color shift RGB → IRG:

    • NIR = R

    • Red = G

    • Green = B

  • Jpeg image format

  • Output Format: Jpeg images in a compressed folder

    • Folder Name: {layer parameter}.zip

    • Image Name: {year}~{AOI name}~{camera orientation}~{image name}.jpg


Base URL

The ExtractNIRImages service responds to the following base URLs:

  • Base URL with only mandatory parameters:
    https://api.gic.org/images/ExtractNIRImages/{layer}?mode={mode}&token={token}

  • Base URLs with all parameters defined as key-value-pairs:

    • Lat/Lon Coordinate Area
      https://api.gic.org/images/ExtractNIRImages/{layer}?mode={mode}&token={token}&xcoordinate={xcoordinate}&ycoordinate={ycoordinate}&width={width}&height={height}&zoom={zoom}&EPSG={EPSG}&imagename={imagename}&startDate={startDate}&endDate={endDate}&rotatedNorth={rotatedNorth}&metadata={metadata}&excludeJGWfiles={excludeJGWfiles}&drawing={drawing}&logo={logo}

    • Polygon Area
      https://api.gic.org/images/ExtractNIRImages/{layer}?mode={mode}&token={token}&wkt={wkt}&crop={crop}&EPSG={EPSG}&zoom={zoom}&imagename={imagename}&startDate={startDate}&endDate={endDate}&rotatedNorth={rotatedNorth}&metadata={metadata}&excludeJGWfiles={excludeJGWfiles}&drawing={drawing}&logo={logo}


Parameters

Parameter

Parameter Type

Data Type

Description

Example Format

Notes

Parameter

Parameter Type

Data Type

Description

Example Format

Notes

Mandatory Parameters:

layer

Ordered REST

string

Layer of the requested image.

bluesky-ultra-g
Urban data collected by Geomni

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)

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 data collected by Geomni

graysky
Gray Sky data collected by UltraCam sensors.

/bluesky-ultra-g

The layer parameter must be defined within the url as an ordered REST parameter rather than a Key-Value pair. This is the only layer that must be defined in this manner.

mode

Key Value Pair (KVP)

string

 Indicates the work mode of the service request.

all
All the available NIR images in the area.

best
One image from each camera orientation, each with best coverage over the input area. See the note to the right for more info on best coverage.

most-recent
The most recent captured image, even with partial coverage

one
Only the NIR image from the image defined in imagename parameter.

mode=most-recent

Definition of mode=best:
Images are defined as best depending on the method of defining an input area:
- lat/lon - The image with a center point closest to the input coordinate is considered best
- wkt polygon - The image that covers the most of the input polygon is considered best

In both cases, if there are multiple images which meet the best criteria, the most recent image will be returned.

zoom

Key-Value-Pair

Integer

 The zoom level of the returned images.

0 = Full Resolution
1 = 1/2 Resolution
2 = 1/4 Resolution
3 = 1/8 Resolution

12 = 1/4096 Resolution - Maximum Zoom

zoom=2

 

epsg

Key-Value-Pair

Integer

The EPSG code determines the projection of the provided coordinates or wkt polygon.

epsg=4326

More info on EPSG codes in External Resources

token

Key-Value-Pair

String

Token used to authenticate the requests.

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.

  • Set of Lat/Lon Coordinates

xcoordinate

Key-Value-Pair

double

The longitudinal decimal degree coordinate for the desired point, 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 desired point, represented by the EPSG projection defined by the EPSG parameter.

ycoordinate=44.9186

 

width

Key-Value-Pair

Integer

The width (in pixels) defining the east/west extent of a rectangle centered on the lat/lon coordinate point. Images intersecting the rectangle will be returned, cropped by the rectangle extent.

width=400

If not specified, full image(s) intersecting the lat/lon coordinate point will be retrieved.

height

Key-Value-Pair

Integer

The height (in pixels) defining the north/south extent of a rectangle centered on the lat/lon coordinate point. Images intersecting the rectangle will be returned, cropped by the rectangle extent.

height=400

If not specified, full image(s) intersecting the lat/lon coordinate point will be retrieved.

  • 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

crop

Key-Value-Pair

string

The method with which to crop the returned images based on the input wkt parameter.

crop- Default value if wkt is provided. Crops the image(s) to the minimum bounding rectangle of the wkt polygon values.

exact- Crops the image(s) to the exact shape of the wkt polygon.

full- Whole image(s) which intersect the wkt polygon will be returned.

wkt polygon:

crop=boundingBox

The crop parameter will only work when used with the wkt parameter

Optional Parameters

imagename

Key Value Pair

string

Only the image referred to by this parameter will be downloaded.

imagename=2020~us-mn-bloomington-2020~nadir~8370-lvl02-color_ir

This parameter is mandatory if mode is set to one

The imagename can be obtained through findImage or similar services.

startDate

Key Value Pair

String

No images collected 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")

 

rotatedNorth

Key Value Pair

string

Determines the rotation of the image:

  • no - default - Rotated to orientation of collection

  • yes - North-orientated.

rotatedNorth=yes

 

metadata

Key Value Pair

string

Type of metadata schema to be delivered along with the images. Metadata and images are delivered in the same zip file.

none - default

json

metadata=json

See Discrete Images Metadata for more information on the format and type of metadata available.

excludeJGWfiles

Key Value Pair

boolean

By default, a jgw file associated to each image is returned. To exclude all JGW files, set excludeJGWfiles = true

excludeJGWfiles=true

JGW files are not available when area is defined by x/y coordinates.

JGW files are not delivered when mode=one; this allows for the returned image to remain unzipped. To receive a JGW file when mode=one, metadata must be requested (results will be returned in a zipped folder).

drawing

Key Value Pair

string

Signal to be drawn in the delivered images as a marker of the requested point.

none - Default value - No signal drawing will be made on the image(s)

cross - A yellow cross signaling the requested point will be made on the image(s).

drawing=cross

The drawing parameter is dependent on using a set of xcoordinate/ycoordinate rather than wkt

The location of the marker will be identified using our underlying DSM layer unless another dem is selected with the demPriority parameter.

logo

Key Value Pair

string

A watermark will be drawn on the bottom of the image(s). By default, the logo will not be printed.

logo=yes

 

demPriority

Key-Value-Pair

string

A digital elevation model (DEM) is used during the world to pixel projection. This parameter allows the user to select the desired elevation model(s) with which to perform the projection. Multiple DEMs may be selected; values separated by comma. By default this service will select the most accurate available DEM.

Listed in order of accuracy:

vexcel_dsm - most accurate

vexcel_dtm

public_dtm

flat_dtm - least accurate

demPriority=vexcel_dsm,flat_dtm

demPriority is an uncommon parameter, and we recommend using in these use cases - crosshairs, crop and strange clipping.

Crosshairs: When you are using drawing=cross and the image returned doesn't match your expectations we recommend utilizing this parameter.

Crop: The crop parameter can sometimes be affected by DEM projection when the projected imagery doesn't fully cover the input crop wkt the user has specified. Changing the DEMPriority can sometimes solve for this. This may result with a change in projection and a potentially less accurate image.

Strange Clipping: If you receive any images like the one below there is an issue with our data and ask you to reach out to our support team (support@gic.org or support@vexcelgroup.com) so we can make our production team aware. We recommend changing the DEMPriority to solve for this issue.


Examples

Minneapolis Institute of Art - Example using coordinates:

https://api.gic.org/images/ExtractNIRImages/bluesky-ultra?xcoordinate=-93.27409305335922&ycoordinate=44.9582938260901&epsg=4326&zoom=2&mode=all&width=700&height=700&rotatedNorth=yes&token={token}

Parameter

Value

Parameter

Value

layer

bluesky-ultra

xcoordinate

-93.27409305335922

ycoordinate

44.9582938260901

epsg

4326

zoom

2

mode

all

width

400

height

400

rotatedNorth

yes

token

{token}

Output:

The output is a compressed directory containing jpg images

________________________________________________________________________________________

RGB representation

https://api.gic.org/images/ExtractImages/bluesky-ultra?xcoordinate=-93.27409305335922&ycoordinate=44.9582938260901&epsg=4326&zoom=2&mode=all&width=700&height=700&orientation=NADIR&nadirRotatedNorth=yes&token={token}

 

F. Scott Fitzgerald’s House - Example using a polygon

https://api.gic.org/images/ExtractNIRImages/bluesky-ultra?epsg=4326&zoom=1&mode=one&imagename=2022~us-mn-minneapolis-2022~images~NN_20220617_151132_86_27F15836702799E_irg&rotatedNorth=yes&wkt=POLYGON((-93.12537831156952 44.9414904394156, -93.12523213117821 44.94150752630889, -93.12519592135651 44.94174674228089, -93.12536892383797 44.941765727632806, -93.12537831156952 44.9414904394156))&crop=boundingbox

Parameter

Value

 

Parameter

Value

 

layer

bluesky-ultra

 

wkt

POLYGON((-93.12537831156952 44.9414904394156, -93.12523213117821 44.94150752630889, -93.12519592135651 44.94174674228089, -93.12536892383797 44.941765727632806, -93.12537831156952 44.9414904394156))

crop

boundingbox

 

epsg

4326

 

zoom

1

 

mode

one

 

imagename

2022~us-mn-minneapolis-2022~images~NN_20220617_151132_86_27F15836702799E_irg

 

rotatedNorth

yes

 

 

RGB representation

https://api.gic.org/images/ExtractImages/bluesky-ultra?epsg=4326&zoom=1&mode=one&rotatedNorth=yes&wkt=POLYGON((-93.12537831156952 44.9414904394156, -93.12523213117821 44.94150752630889, -93.12519592135651 44.94174674228089, -93.12536892383797 44.941765727632806, -93.12537831156952 44.9414904394156))&crop=boundingbox&orientation=nn

________________________________________________________________________________________

Stewart Park, Minneapolis MN - Example using optional parameters:

https://api.gic.org/images/ExtractNIRImages/bluesky-ultra?xcoordinate=-93.258856&ycoordinate=44.954252&epsg=4326&zoom=1&mode=best&width=1200&height=1200&logo=yes&metadata=json&drawing=cross&token={token}

Parameter

Value

Parameter

Value

layer

bluesky-ultra

xcoordinate

-93.258856

ycoordinate

44.954252

epsg

4326

zoom

1

mode

best

width

1200

height

1200

logo

yes

metadata

json

drawing

cross

token

{token}

Metadata (in JSON format):

[{"requested_point_wkt":"POINT(7761.811630220274 4890.897192878125)","gsd":0.0752518773297423,"image_id":"2019~us-mn-minneapolis-2019~images~NW_20190808_155443_92_27F14C5CEC6930E_irg","processing_date":"2021-06-21T23:18:39","processing_toolset_version":"3.3.0","capture_date":"2019-08-08T15:54:43","original_image_name":"nadir/22194-lvl02-color.tif","original_shot_id":"22194-Lvl02-Color","flight_line_id":"1","utm_zone":"15N","camera_pos_x":479555.9888,"camera_pos_y":4977822.573,"camera_z":1448.63501,"ground_z":262.011597,"omega":-0.001688315042463806,"phi":0.008293094654953778,"kappa":1.6478486375884165,"centre_wkt":"POINT(-93.25930679 44.95352711)","centre_wkt_latlon":"POINT(-93.25930679 44.95352711)","bbox_wkt":"POLYGON((-93.26292109 44.94873433,-93.26394805 44.9578427,-93.25570339 44.95830455,-93.25467894 44.94922342,-93.26292109 44.94873433))","bbox_wkt_latlon":"POLYGON((-93.26292109 44.94873433,-93.26394805 44.9578427,-93.25570339 44.95830455,-93.25467894 44.94922342,-93.26292109 44.94873433))","orientation":"I","projectname":"us-mn-minneapolis-2019","copyrightsentence":"VEXCEL_IMAGING_INC","processingcenter":"","layername":"bluesky-ultra","dtmfile":"","cameratechnology":"VEXCEL","projectext":"us-mn-minneapolis-2019","raster_size_width":13470.0,"raster_size_height":8670.0,"pixel_size":0.0052,"focal_length":82.0,"pp0_x":0.0,"pp0_y":0.0,"k0":0.0,"k1":0.0,"k2":0.0,"k3":0.0,"p1":0.0,"p2":0.0,"b1":0.0,"b2":0.0,"camera_name":"0","id":365612518,"max_zoom":0,"min_zoom":7,"tile_size_x":256,"tile_size_y":256,"relationPolygonInImage":0.0,"relationImageInPolygon":0.0}]

RGB representation

https://api.gic.org/images/ExtractImages/bluesky-ultra?xcoordinate=-93.258856&ycoordinate=44.954252&epsg=4326&zoom=1&mode=best&width=1200&height=1200&orientation=NADIR&token={token}


External Resources

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

 

Related content

Need help? Create a support ticket | support@vexcelgroup.com