Introduction

The TransformDiscretePoints service will perform a coordinate transformation between world points (lon/lat) and pixel points within a discrete image. This transformation can occur in either direction:

world point to pixel point
pixel point to world point

This service is useful when identifying the exact location on Earth as represented in a discrete image’s pixel geometry or vice versa.

Technical Details

The TransformDiscretePoints service is accessed by specifying the transformation direction (mode), the discrete image (discreteid), and coordinates (points). Because this service can transform points in either direction it is important to correctly pair the mode and point formats (e.g. if mode=discretepixel then points must be world points (lon, lat)). Pixel points are defined within a discrete image as the origin point (0,0) being the top-left corner of the image. Batch transformations can occur by providing more than one pair of points in a single service call.

Output File Specifications:

File format: xml, json, jsonp

Base URL

This service will answer requests on the following URLs:

Ordered as HTTP REST parameters (mandatory parameters only):
https://api.gic.org/metadata/TransformDiscretePoints/{format}/{mode}/{discreteid}/{points}/{EPSG}?token={token}
Base URL with parameters defined as a mix of REST and Key Value Pairs
https://api.gic.org/metadata/TransformDiscretePoints/{format}/{mode}/{discreteid}?points={points}&EPSG={EPSG}&jsonpFunction={jsonpFunction}&precision={precision}&token={token}
Base URL with all parameters defined:
https://api.gic.org/metadata/TransformDiscretePoints?format={format}&mode={mode}&discreteid={discreteid}&points={points}&EPSG={EPSG}&jsonpFunction={jsonpFunction}&precision={precision}&token={token}

Parameters

Parameter	Parameter Type	Data Type	Description	Example Format	Notes

Parameter	Parameter Type	Data Type	Description	Example Format	Notes
Mandatory:
`format`	Ordered REST (1st) - or - Key Value Pair (KVP)	String	The format of the response file. `xml` - Extensible Markup Language `json` - JavaScript Object Notation `jsonp` - JavaScript Object Notation with Padding	Ordered REST: `/xml` KVP: `format=xml`	The jsonp padding name can be defined with the use of the `jsonpFunction` parameter.
`Mode`	Ordered REST (2nd) - or - Key Value Pair	String	The work modes of the service. These work modes determine how the provided coordinates will be interpreted. `discretepixel` - the provided coordinates will be interpreted as world points represented in the given EPSG projection and will transform them into pixel points inside the given image. `world` - the provided coordinates will be interpreted as pixel points inside the given image and will transform them into world points represented in the given EPSG projection.	Ordered REST: `/discretepixel` KVP: `Mode=discretepixel`
`discreteid`	Ordered REST (3rd) - or - Key Value Pair	String	The ID(s) for the discrete image.	Ordered REST: `/2022~us-fl-jacksonville-2022~images~NN_20220219_170352_75_389376DF2815A7C_rgb` KVP: `discreteid=2022~us-fl-jacksonville-2022~images~NN_20220219_170352_75_389376DF2815A7C_rgb`	Use a service like FindImagesInPoint or FindImagesInPolygon to identify the `discreteId`.
`points`	Ordered REST (4th) - or - Key Value Pair	Double	A group of coordinate pairs to be transformed. Depending on `mode`, these points would be either: pixel points inside the provided image (x,y) world points in the provided EPSG projection (lon,lat)	Ordered REST (World Points: `/-81.6008452,30.3328177` KVP (World Points): `points=-81.6008452,30.3328177` Ordered REST (Pixel Points): `/1,1` KVP (Pixel Points): `points=1,1`	Multiple sets of coordinate pairs may be used, separated by commas. For example: `points=-81.6008452,30.3328177,-81.5996596,30.3322621` `points=1,1,3,4`
`EPSG`	Ordered REST (5th) - or - Key Value Pair	Integer	The EPSG code determines the projection of the provided coordinates.	Ordered REST: `/4623` KVP: `EPSG=4623`	More info on EPSG codes in External Resources
`token`	Key Value Pair	String	The token used to authenticate the requests.	`token={token}`	Use the Authenticate Service to receive a token. A token will temporarily be stored in cache and may be omitted on subsequent calls.
Optional:
`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}`	This parameter is only available if `format=jsonp`
`precision`	Key Value Pair	String	The level of accuracy desired while transforming points. `high` (default) - utilizes the DTM terrain projection and is slower but more accurate. `low` - utilizes a simplified flat terrain projection and is faster but less accurate.	`precision=high`

Examples

Friendship Fountain, Jacksonville, Florida - Demonstrating mode=discretepixel using multiple points with precision=high
https://api.gic.org/metadata/TransformDiscretePoints/xml/discretepixel/2022~us-fl-jacksonville-2022~images~NN_20220219_170352_75_389376DF2815A7C_rgb/-81.659819,30.320020,-81.658588,30.320846,-81.657524,30.320095,-81.656697,30.319733/4326?precision=high&token={token}

Table of Parameters

Parameter	Value

Parameter	Value
`format`	`xml`
`mode`	`discretepixel`
`discreteid`	`2022~us-fl-jacksonville-2022~images~NN_20220219_170352_75_389376DF2815A7C_rgb`
`points`	`-81.659819,30.320020,-81.658588,30.320846,-81.657524,30.320095,-81.656697,30.319733`
`EPSG`	`4326`
`precision`	`high`
`token`	`{token}`

Input World Points

https://api.gic.org/images/ExtractImages/bluesky-ultra?mode=one&zoom=0&EPSG=4326&imagename=2022~us-fl-jacksonville-2022~images~NN_20220219_170352_75_389376DF2815A7C_rgb&xcoordinate=-81.65981289650043&ycoordinate=30.320036912770377&token={token}

Results:

XML Output file:

<?xml version="1.0" encoding="UTF-8"?>
<TransformedPoints>
  <points>
    <Point>
      <x>5022.6732652875025</x>
      <y>5415.800164327448</y>
      <z>0.0</z>
    </Point>
    <Point>
      <x>6599.747946196218</x>
      <y>4191.870722112792</y>
      <z>0.0</z>
    </Point>
    <Point>
      <x>7964.3274801469215</x>
      <y>5297.516803667657</y>
      <z>0.0</z>
    </Point>
    <Point>
      <x>9026.831681477946</x>
      <y>5830.729448761475</y>
      <z>0.0</z>
    </Point>
  </points>
  <EPSG>0</EPSG>
</TransformedPoints>

Transformed Pixel Points

Point Transformation Table:

Point	World Point	Pixel Point (xml format)

Point	World Point	Pixel Point (xml format)
1	`-81.659819,30.320020`	`<x>5022.6732652875025</x>` `<y>5415.800164327448</y>`
2	`-81.658588, 30.320846`	`<x>6599.747946196218</x>` `<y>4191.870722112792</y>`
3	`-81.657524, 30.320095`	`<x>7964.3274801469215</x>` `<y>5297.516803667657</y>`
4	`-81.656697, 30.319733`	`<x>9026.831681477946</x>` `<y>5830.729448761475</y>`

________________________________________________________________________________________

Fort Clinch, Fernandina Beach, Florida - Demonstrating mode=world and precision=low
https://api.gic.org/metadata/TransformDiscretePoints?format=jsonp&mode=world&discreteid=2019~us-fl-fernandinabeach_midas-2019~images~NN_20190225_151830_75_38960187BDEA86B_rgb&points=6517,2755&epsg=4326&precision=low&jsonpFunction=SampleFunction&token={token}

Table of Parameters

Parameter	Value

Parameter	Value
`format`	`jsonp`
`mode`	`world`
`discreteid`	`2019~us-fl-fernandinabeach_midas-2019~images~NN_20190225_151830_75_38960187BDEA86B_rgb`
`points`	`6517,2755`
`EPSG`	`4326`
`precision`	`low`
`jsonpFunction`	`SampleFunction`
`token`	`{token}`

Input Pixel Points

https://api.gic.org/images/ExtractImages/bluesky-ultra-g?mode=one&zoom=0&EPSG=4326&orientation=nn&xcoordinate=-81.454308&ycoordinate=30.704773&imagename=2019~us-fl-fernandinabeach_midas-2019~images~NN_20190225_151830_75_38960187BDEA86B_rgb&token={token}

Results:

jsonp Output file:

function SampleFunction() {return
  {
    "points": [
      {
        "x": -81.45385047479137,
        "y": 30.70445609887719,
        "z": 1.3469929695129395
      }
    ],
    "EPSG": 4326
  }
}

Transformed World Points

Point Transformation Table:

Pixel Point	World Point (json format)

Pixel Point

World Point (json format)

6517,2755

"x": -81.45385047479137,

"y": 30.70445609887719,

"z": 1.3469929695129395

External Resources

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

EPSG Codes: EPSG Geodetic Parameter Dataset

Vexcel API Documentation

TransformDiscretePoints Service - v1.4

Analytics