Geometry Referential#

What is referential package?#

Referential is a package that can deal with:

  • Format conversions;

  • Coordinate transformations;

  • Altitude conversions.

Geometry Referential can convert coordinates; formats and altitudes at the same time in a quick and efficient way.

There are two main curried functions, a syncronous function: convert(from,to)(coordinates) and one asyncronous function: convertAsync(from,to)(coordinates) althought both functions (sync and async) have the same signature, altitude conversions can only be performed when using the asyncronous function (convertAsync). We use curried functions to make it easier, and more eficiently process big amonts transformations. We can create only one conversion function and then apply it to several points, for example:

const conversion1 = convert(from, to);
const coordinates1 = conversion1(coordinatesA);
const coordinates2 = conversion1(coordinatesB);
const coordinates3 = conversion1(coordinatesC);
const coordinates4 = conversion1(coordinatesD);
const coordinates5 = conversion1(coordinatesE);

Format conversions#

All supported formats can be transformed between them. Current supported formats are:

  • ArrayXY

  • ArrayXYZ

  • ArrayLatitudeLongitude

  • ArrayLatitudeLongitudeAltitude

  • String e.g.

  • ObjectXY

  • ObjectXYZ

  • ObjectLatLon

  • ObjectLatLonAlt

  • ObjectLatitudeLongitude

  • ObjectLatitudeLongitudeAltitude

  • ThreeVector2

  • ThreeVector3

  • ThreeVector4

  • CesiumCartographic

  • CesiumCartesian2

  • CesiumCartesian3

  • CesiumCartesian4

Please check reference/custom-formats if you need to add custom formats.

Coordinate transformations#

This package uses proj4js ( This means that most of coordinate transformations are possible as long as you have a valid proj definition.

Allowed coordinate type values are reference or local Referenced systems must have a definition which is a proj4 string definition.

Only when using convertAsync we can provide EPSG code. Please note EPSG codes are only valid for convertAsync function.

Local transformations#

A special case of transformations are the ones coming from or to local systems or local space, this transformations are particulary important when dealing with computed graphics. This package can transform from and to local coordinate systems.

When dealing with local systems or local space, its mandatory to specify the origin in a known reference system.

More info about local space can be found on

Altitude conversions#

Altitude conversions can only be processed when using convertAsync function.

Currently supported altitude types are:

  • cesiumTerrain, uses CesiumJS;

  • geoid (egm96);

  • default, uses ellipsoid (Proj4);

The folowing image describes diferences between the three diferent altitudes.

alt text