FindImagesInPolygon Service - v1.4

Owned by Scott Jonker
Feb 26, 2024
48 min read

Introduction

FindImagesInPolygon will take a well known text (wkt) polygon and identify all available discrete images available for that location. The output is a metadata file with information about each discrete image. This service is available for all layers in the Vexcel library.

Technical Details

The output metadata can be provided in three formats, xml, json or jsonp.

Output Specifications:

  • Metadata Formats (xml, json, jsonp)

Detailed information about the metadata can be found in Discrete Image Metadata.

Base URL

This service responds to requests from following URLs:

  • Mandatory parameters only - Defined as ordered http REST parameters:
    https://api.gic.org/metadata/FindImagesInPolygon/{format}/{EPSG}/{wkt}?token={token}

  • Mandatory parameters only - Defined as Key Value Pairs:
    https://api.gic.org/metadata/FindImagesInPolygon?format={format}&EPSG={EPSG}&wkt={wkt}&token={token}

  • All parameters - Defined as a mix of REST and Key Value Pairs:
    https://api.gic.org/metadata/FindImagesInPolygon/{format}/{EPSG}/{wkt}?orientation={orientation}&rendering={rendering}&layer={layer}&mode={mode}&jsonpFunction={jsonpFunction}&token={token}

Parameters

Parameter

Parameter Type

Data Type

Description

Format

Notes

Parameter

Parameter Type

Data Type

Description

Format

Notes

Mandatory:

format

Ordered REST (1st) - or - Key Value Pair (KVP)

String

Format of the response.

xml - Extensible Markup Language

json - JavaScript Object Notation

jsonp - JavaScript Object Notation with Padding

Ordered REST: /xml
KVP: format=xml

The jsonp padding can be defined with the use of the jsonFunction parameter.

EPSG

Ordered REST (2nd) - or - Key Value Pair (KVP)

Integer

The EPSG code for the projection reference representing the coordinates of the given wkt (below).

Ordered REST: /4623
KVP: EPSG=4623

 

wkt

Ordered REST (3rd) - or - Key Value Pair (KVP)

String

The well-known-text (wkt) representation of the requested polygon.

Ordered REST: /POLYGON((-78.837290 35.8220769,-78.8367352 35.8220573,-78.8367326 35.8223944,-78.8372824 35.82240314,-78.837290 35.8220769))
KVP: wkt=POLYGON((-78.837290 35.8220769,-78.8367352 35.8220573,-78.8367326 35.8223944,-78.8372824 35.82240314,-78.837290 35.8220769))

 

token

Key Value Pair

String

The token used to authenticate the requests.

token={token}

Use the Authentication Service to receive a token.

Optional:

orientation

Ordered REST (4th) - or - Key Value Pair

String

The camera-axis and/or cardinal orientation of the images to be delivered.

ALL: all orientations

NADIR: all the Nadir orientations (NN, NS, NE, NW)

OBLIQUE: all the oblique orientations: (N, S, E, W)

Single values for specific orientations:   N, S, E, W, NN, NS, NE, NW, I

orientation=NADIR

 

rendering

Key Value Pair

String

The color band rendering of the image metadata.

all - Default - Metadata is received from all available images

rgb - Metadata is received only for rgb (red, green, blue) images: including both nadir and oblique.

nir - Metadata is received only for Near-infrared images. Infrared is only available in nadir images from layers bluesky-high, bluesky-ultra and graysky.

rendering=all

 

layer

Key Value Pair

String

The layer(s) with which to search for coverage over the input polygon. To specify more than one layer, the values must be separated by commas.

bluesky-ultra-g (default )
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 collecgted 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

layer=bluesky-high

mode

Key Value Pair

String

The mode specifies the coverage requirement over the input wkt in order to return an image.

Intersects - Default - Metadata for all images intersecting the input wkt will be delivered.

contains -  Metadata only for images completely contained within the input wkt will be delivered.

 

 

jsonpFunction

Key Value Pair

String

The customizable name of the padding function for format=jsonp calls. If left undefined, the default name is VexcelFunction.

jsonpFunction={CustomName}

Examples

Suburban Neighborhood - Raleigh/Durham, North Carolina - Demonstrating orientation and format=xml
https://api.gic.org/metadata/FindImagesInPolygon/xml/4326/POLYGON((-78.837290 35.8220769,-78.8367352 35.8220573,-78.8367326 35.8223944,-78.8372824 35.82240314,-78.837290 35.8220769))/nw?token={token}

Table of Parameters:

Parameter

Value

Parameter

Value

format

xml

epsg

4326

wkt

POLYGON((-78.837290 35.8220769,-78.8367352 35.8220573,-78.8367326 35.8223944,-78.8372824 35.82240314,-78.837290 35.8220769))

orientation

nw

token

{token}

Metadata Output Sample:

<?xml version="1.0" encoding="UTF-8"?> <Images> <images> <DiscreteImageMetadataDTO> <child_aoi>us-nc-raleigh_leica-2019</child_aoi> <centre_wkt>POINT(-78.836291 35.82284701)</centre_wkt> <relationPolygonInImage>0.009954472654131337</relationPolygonInImage> <processing_toolset_version>3.3.0</processing_toolset_version> <layername>bluesky-ultra-g</layername> <bbox_wkt>POLYGON((-78.83835225 35.82062885,-78.83834245 35.82507432,-78.83420361 35.82509296,-78.83423709 35.82061706,-78.83835225 35.82062885))</bbox_wkt> <flight_line_id>0249</flight_line_id> <b1>0.0</b1> <b2>0.0</b2> . . .

________________________________________________________________________________________

The North Carolina Museum of Art - Raleigh, North Carolina - Demonstrating rendering, jsonpFunction and format=jsonp
https://api.gic.org/metadata/FindImagesInPolygon/jsonp/4326/POLYGON((-78.702348 35.808872,-78.701961 35.809020,-78.702916 35.810203,-78.703270 35.810055,-78.702348 35.808872))?rendering=rgb&jsonpFunction=samplename&token={token}

Table of Parameters:

Parameter

Value

Parameter

Value

format

jsonp

epsg

4326

wkt

POLYGON((-78.702348 35.808872,-78.701961 35.809020,-78.702916 35.810203,-78.703270 35.810055,-78.702348 35.808872))

rendering

rgb

jsonpFunction

samplename

token

{token}

Metadata Output Sample:

function samplename() {return function samplename() {return [ { "child_aoi": "us-nc-raleigh_leica-2019", "centre_wkt": "POINT(-78.70148764 35.80740285)", "relationPolygonInImage": 0.012192450252865838, "processing_toolset_version": "3.3.0", "layername": "bluesky-ultra-g", "bbox_wkt": "POLYGON((-78.69977074 35.80469945,-78.70320832 35.80487464,-78.70269038 35.80927346,-78.70024513 35.80920574,-78.69977074 35.80469945))", "flight_line_id": "0480", "b1": 0, "b2": 0, "id": 641721392, . . .

________________________________________________________________________________________

Eno River Bridge - Eno River State Park - Durham, North Carolina - Demonstrating layer and format=json
https://api.gic.org/metadata/FindImagesInPolygon/json/4326/POLYGON((-79.007845 36.075539,-79.007607 36.075539,-79.007607 36.075354,-79.007845 36.075354,-79.007845 36.075539))?&layer=bluesky-ultra-g&token={token}

Table of Parameters:

Parameter

Value

Parameter

Value

format

json

espg

4326

wkt

POLYGON((-79.007845 36.075539,-79.007607 36.075539,-79.007607 36.075354,-79.007845 36.075354,-79.007845 36.075539))

layer

bluesky-ultra-g

token

{token}

Metadata Output Sample:

[ { "child_aoi": "us-nc-durham_leica-2020", "centre_wkt": "POINT(-79.0058795 36.07732447)", "relationPolygonInImage": 0.0009657824081379157, "processing_toolset_version": "3.3.0", "layername": "bluesky-ultra-g", "bbox_wkt": "POLYGON((-79.00015071 36.07989682,-78.99983976 36.07467246,-79.01016992 36.07546962,-79.01018998 36.07919951,-79.00015071 36.07989682))", "flight_line_id": "0062", "b1": 0, "b2": 0, "id": 458958102, "max_zoom": 0, . . .

External Resources:

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