ExtractNIRImages Service - v1.4

Owned by Scott Jonker
Jun 14, 2023
7 min read

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}

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

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

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

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

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

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

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

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

drawing

Key Value Pair

string

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

drawing=cross

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.

demPriority=vexcel_dsm,flat_dtm

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}

Output:

________________________________________________________________________________________

RGB representation

 

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

 

RGB representation

________________________________________________________________________________________

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}

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

External Resources

 

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